Basic API

Each CKEditor 5 build provides a different editor class that handles the creation of editor instances:

• Classic editor – ClassicEditor
• Inline editor – InlineEditor
• Balloon editor – BalloonEditor
• Document editor – DecoupledEditor

Most of the examples in the documentation use the ClassicEditor class, but things should work in a similar way with other builds.

# Creating an editor

Regardless of the chosen build, creating an editor is done using the static create() method.

# Example – classic editor

Add an element that CKEditor should replace to your HTML page:

<div id="editor">
    <p>Here goes the initial content of the editor.</p>
</div>

Then call ClassicEditor.create() to replace the <textarea> element with a classic editor:

ClassicEditor
    .create( document.querySelector( '#editor' ) )
    .then( editor => {
        console.log( editor );
    } )
    .catch( error => {
        console.error( error );
    } );

In this case the <textarea> element is hidden and replaced with an editor. The <textarea> data is used to initialize the editor content. A <div> element can be used in the same way.

# Example – inline editor

Similarly to the previous example, add an element where CKEditor 5 should initialize to your page:

<div id="editor">
    <p>Here goes the initial content of the editor.</p>
</div>

Then call InlineEditor.create() to attach inline editor to the <div> element:

InlineEditor
    .create( document.querySelector( '#editor' ) )
    .then( editor => {
        console.log( editor );
    } )
    .catch( error => {
        console.error( error );
    } );

# Example – balloon editor

The procedure is the same as for inline editor. The only difference is that you need to use the BalloonEditor.create() method.

Add an element where CKEditor should initialize to your page:

<div id="editor">
    <p>Here goes the initial content of the editor.</p>
</div>

Then call BalloonEditor.create() to attach balloon editor to the <div> element:

BalloonEditor
    .create( document.querySelector( '#editor' ) )
    .then( editor => {
        console.log( editor );
    } )
    .catch( error => {
        console.error( error );
    } );

# Example – decoupled editor

Add the elements where CKEditor 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() method to create a decoupled editor instance with the toolbar and the editable in two separate containers:

DecoupledEditor
    .create( document.querySelector( '#editor' ) )
    .then( editor => {
        const toolbarContainer = document.querySelector( '#toolbar-container' );

        toolbarContainer.appendChild( editor.ui.view.toolbar.element );
    } )
    .catch( error => {
        console.error( error );
    } );

# Interacting with the editor

Once the editor is created, it is possible to interact with it through its API. The editor variable from the examples above should enable that.

# Setting the editor data

To replace the editor content with new data, use the setData() method:

editor.setData( '<p>Some text.</p>' );

# Getting the editor data

If the editor content needs to be retrieved for any reason, like for sending it to the server through an Ajax call, use the getData() method:

const data = editor.getData();

# Destroying the editor

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 destroyed, resources used by the editor instance are released and the original element used to create the editor is automatically displayed and updated to reflect the final editor data.

# Listening to changes

The Document#change:data event is fired when the document changes in such a way that is “visible” in the editor data.

editor.model.document.on( 'change:data', () => {
    console.log( 'The data has changed!' );
} );

There is also a group of changes like selection position changes or marker changes which do not affect the result of editor.getData(). To listen to all these changes, you can use a wider Document#change event.

# UMD support

Because builds are distributed as UMD modules, editor classes can be retrieved in various ways:

• by a CommonJS-compatible loader (e.g. webpack or Browserify),
• by RequireJS (or any other AMD library),
• from the global namespace if none of the above loaders is available.

For example:

// In the CommonJS environment.
const ClassicEditor = require( '@ckeditor/ckeditor5-build-classic' );
ClassicEditor.create( ... ); // [Function]

// If AMD is present, you can do this.
require( [ 'path/to/ckeditor5-build-classic/build/ckeditor' ], ClassicEditor => {
    ClassicEditor.create( ... ); // [Function]
} );

// As a global variable.
ClassicEditor.create( ... ); // [Function]

// As an ES6 module (if using webpack or Rollup).
import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
ClassicEditor.create( ... ); // [Function]