Creating a simple plugin

This guide will show you how to create a simple rich-text editor plugin for CKEditor 5.

CKEditor plugins need to implement the PluginInterface. The easiest way to do that is to inherit from the base Plugin class. However, you can also write simple constructor functions. This guide uses the former method.

The plugin that you will write will use a part of the image feature and will add a simple UI to it — an “Insert image” button that will open a prompt window asking for the image URL when clicked. Submitting the URL will result in inserting the image into the content and selecting it.

# Step 1. Installing dependencies

Start from installing the necessary dependencies:

• The @ckeditor/ckeditor5-image package that contains the image feature (on which the plugin will rely).
• The @ckeditor/ckeditor5-core package which contains the Plugin and Command classes.
• The @ckeditor/ckeditor5-ui package which contains the UI library and framework.

npm install --save @ckeditor/ckeditor5-image \
    @ckeditor/ckeditor5-core \
    @ckeditor/ckeditor5-ui

Now, open the app.js file and start adding code there. Usually, when implementing more complex features you will want to split the code into multiple files (modules). However, to make this guide simpler the entire code will be kept in app.js.

The first thing to do will be to load the core of the image feature:

import Image from '@ckeditor/ckeditor5-image/src/image';

// ...

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // Add Image to the plugin list.
        plugins: [ Essentials, Paragraph, Bold, Italic, Image ],

        // ...
    } )
    // ...

Save the file and run webpack. Refresh the page in your browser (remember about the cache) and… you should not see any changes. This is correct! The core of the image feature does not come with any UI, nor have you added any image to the initial HTML. Change this now:

<div id="editor">
    <p>Simple image:</p>

    <figure class="image">
        <img src="https://via.placeholder.com/1000x300/02c7cd/fff?text=Placeholder%20image" alt="CKEditor 5 rocks!">
    </figure>
</div>

# Step 2. Creating a plugin

You can now start implementing your new plugin. Create the InsertImage plugin:

import Plugin from '@ckeditor/ckeditor5-core/src/plugin';

class InsertImage extends Plugin {
    init() {
        console.log( 'InsertImage was initialized' );
    }
}

And add your new plugin to the config.plugins array. After rebuilding the application and refreshing the page you should see “InsertImage was initialized” logged to the console.

# Step 3. Registering a button

Create a button now:

// This SVG file import will be handled by webpack's raw-text loader.
// This means that imageIcon will hold the source SVG.
import imageIcon from '@ckeditor/ckeditor5-core/theme/icons/image.svg';

import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';

class InsertImage extends Plugin {
    init() {
        const editor = this.editor;

        editor.ui.componentFactory.add( 'insertImage', locale => {
            const view = new ButtonView( locale );

            view.set( {
                label: 'Insert image',
                icon: imageIcon,
                tooltip: true
            } );

            // Callback executed once the image is clicked.
            view.on( 'execute', () => {
                const imageURL = prompt( 'Image URL' );
            } );

            return view;
        } );
    }
}

And add the InsertImage plugin to config.plugins and insertImage to config.toolbar:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ...
        plugins: [ Essentials, Paragraph, Bold, Italic, Image, InsertImage ],
        toolbar: [ 'bold', 'italic', 'insertImage' ]
    } )
    // ...

Rebuild the application and refresh the page. You should see a new button in the toolbar. Clicking the button should open a prompt window asking you for the image URL.

# Step 4. Inserting a new image

Now, expand the button’s #execute event listener, so it will actually insert the new image into the content:

class InsertImage extends Plugin {
    init() {
        const editor = this.editor;

        editor.ui.componentFactory.add( 'insertImage', locale => {
            const view = new ButtonView( locale );

            view.set( {
                label: 'Insert image',
                icon: imageIcon,
                tooltip: true
            } );

            // Callback executed once the image is clicked.
            view.on( 'execute', () => {
                const imageUrl = prompt( 'Image URL' );

                editor.model.change( writer => {
                    const imageElement = writer.createElement( 'imageBlock', {
                        src: imageUrl
                    } );

                    // Insert the image in the current selection location.
                    editor.model.insertContent( imageElement, editor.model.document.selection );
                } );
            } );

            return view;
        } );
    }
}

If you refresh the page, you should now be able to insert new images into the content:

The image is fully functional. You can undo inserting by pressing Ctrl+Z and the image is always inserted as a block element (the paragraph that contains the selection is automatically split). This is all handled by the CKEditor 5 engine.

Congratulations! You have just created your first CKEditor 5 plugin!

# Bonus. Enabling image captions

All the plugins operate both on the model and on the view, and know as little about themselves as possible. Thanks to this fact, you can easily enable image captions by simply loading the ImageCaption plugin which handles the captions feature and the ImageToolbar which gives you the ability to control such image properties like having the caption or not. It is also necessary to specify what to include in this new toolbar. In this case, it would be a toggle executing the ToggleImageCaptionCommand which disables or enables the image caption:

import ImageCaption from '@ckeditor/ckeditor5-image/src/imagecaption';
import ImageToolbar from '@ckeditor/ckeditor5-image/src/imagetoolbar';
// ...

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // Add ImageCaption to the plugin list.
        plugins: [ Essentials, Paragraph, Bold, Italic, Image, InsertImage, ImageCaption, ImageToolbar ],
        // ...
        image: {
            toolbar: [ 'toggleImageCaption' ]
        }
        // ...
    } )
    // ...

This should be the result of the change:

# Final code

If you got lost at any point, this should be your final app.js:

import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

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 Image from '@ckeditor/ckeditor5-image/src/image';
import ImageCaption from '@ckeditor/ckeditor5-image/src/imagecaption';
import ImageToolbar from '@ckeditor/ckeditor5-image/src/imagetoolbar';

import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';

import imageIcon from '@ckeditor/ckeditor5-core/theme/icons/image.svg';

class InsertImage extends Plugin {
    init() {
        const editor = this.editor;

        editor.ui.componentFactory.add( 'insertImage', locale => {
            const view = new ButtonView( locale );

            view.set( {
                label: 'Insert image',
                icon: imageIcon,
                tooltip: true
            } );

            // Callback executed once the image is clicked.
            view.on( 'execute', () => {
                const imageUrl = prompt( 'Image URL' );

                editor.model.change( writer => {
                    const imageElement = writer.createElement( 'imageBlock', {
                        src: imageUrl
                    } );

                    // Insert the image in the current selection location.
                    editor.model.insertContent( imageElement, editor.model.document.selection );
                } );
            } );

            return view;
        } );
    }
}

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Essentials, Paragraph, Bold, Italic, Image, InsertImage, ImageCaption, ImageToolbar ],
        toolbar: [ 'bold', 'italic', 'insertImage' ],
        image: {
            toolbar: [ 'toggleImageCaption' ]
        }
    } )
    .then( editor => {
        console.log( 'Editor was initialized', editor );
    } )
    .catch( error => {
        console.error( error.stack );
    } );

# What’s next?

If you would like to read more tutorials, check out the following one:

• Implementing a block widget
• Implementing an inline widget

If you want to read more about the CKEditor 5 architecture, check out the Introduction to CKEditor 5 architecture guide.

If you want your plugin to be easily integrated by other developers, learn about the package metadata file that can be added to your package.