Contribute to this guideReport an issue

guideImages

The @ckeditor/ckeditor5-image package contains multiple plugins that implement various image-related features:

All features listed above are enabled by default in all builds.

# Base image support

The Image feature adds support for plain images with just the alt attribute set. This translates to the following HTML:

<figure class="image">
    <img src="..." alt="...">
</figure>

This feature follows the markup proposed by the Editor Recommendations project.

You can see the demo of an editor with the base image feature enabled below:

This is CKEditor 5.

Autumn fields

The base image feature, unlike in CKEditor 4, does not support any user interface for inserting or managing images. Its sole purpose is to lay ground for other plugins (mentioned above) 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.

# Image contextual toolbar

The ImageToolbar 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 (which is introduced by the base image plugin) button and image styles buttons.

See a demo of an editor with the contextual toolbar enabled:

This is CKEditor 5.

Autumn fields

The image toolbar is configured to contain the image text alternative button:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        image: {
            toolbar: [ 'imageTextAlternative' ]
        }
    } )

# Image captions

The ImageCaption plugin adds support for image captions:

<figure class="image">
    <img src="..." alt="...">
    <figcaption>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. See the demo below:

Image with caption:

Autumn fields
Autumn fields by Aleksander Nowodziński

Image without caption:

Autumn fields

# Image styles

In simple integrations it is enough to let the user insert images, set their text alternative and the editor’s job is done. An example of such a simple solution are e.g. GitHub comments. The styling of the images (for example, their maximum width and margins) is controlled by GitHub through stylesheets.

In more advanced scenarios, the user may need to be able to decide whether the image should take the whole width (if it is the article’s main photo) or it should take, for example, 50% of the width and be pulled out of the content (so called “pulled images”). Various integration scenarios require different types of images to be used.

This is what the ImageStyle feature is designed for.

However, unlike in CKEditor 4, in CKEditor 5 the end user does not set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the editor integration. This gives the developer control over how the users style images and makes the user’s life easier by setting multiple properties at once.

A style is applied to the image in form of a class. By default, the editor is configured to support two styles: “full width” (which does not apply any class — it is the default style) and “side image” (which applies the image-style-side class).

A normal (full width) image:

<figure class="image"><img src="..." alt="..."></figure>

A side image:

<figure class="image image-style-side"><img src="..." alt="..."></figure>

The actual styling of the images is the developer’s job. The editor comes with some default styles, but they will only be applied to images inside the editor. The developer needs to style them appropriately on the target pages.

You can find the source of the default styles applied by the editor here: ckeditor5-image/theme/imagestyle.css.

Below you can see a demo of the editor with the image styles feature enabled. The default configuration is used. You can change the styles of images through the image’s contextual toolbar.

This is full width image (default style):

Autumn fields

This is side image:

Autumn fields

Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here.

# Configuring image styles

The available image styles can be configured using the image.styles option.

The following editor supports the default full image style plus left- and right-aligned images:

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        image: {
            // You need to configure the image toolbar, too, so it uses the new style buttons.
            toolbar: [ 'imageTextAlternative', '|', 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:alignRight' ],

            styles: [
                // This option is equal to a situation where no style is applied.
                'full',

                // This represents an image aligned to the left.
                'alignLeft',

                // This represents an image aligned to the right.
                'alignRight'
            ]
        }
    } )
    .then( ... )
    .catch( ... );

The code sample above uses predefined image styles: 'full', 'alignLeft' and 'alignRight'. The latter two apply, respectively, the .image-style-align-left and .image-style-align-right classes to the <figure> element.

See the result below:

An image to play with:

Autumn fields

Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here.

In the example above the options used represent simple “align left” and “align right” styles. Most text editors support left, center and right alignments, however, try not to think about CKEditor 5’s image styles in this way. Try to understand what use cases the system needs to support and define semantic options accordingly. Defining useful and clear styles is one of the steps towards a good user experience and clear, portable output. For example, the “side image” style can be displayed as a floated image on wide screens and as a normal image on low resolution screens.

# Defining custom styles

Besides using the 5 predefined styles:

  • 'full',
  • 'side',
  • 'alignLeft',
  • 'alignCenter',
  • 'alignRight'

you can also define your own styles or modify the existing ones.

Reusing (or modifying) predefined styles has this advantage that CKEditor 5 will use its official translations for the defined button titles.

You can find advanced examples in the image.styles configuration option documentation.

# Image upload

See the Image upload guide.

# Responsive images

Responsive images support in CKEditor 5 is brought by the Easy Image feature without any additional configuration. Learn more how to use the feature in your project in the “Easy Image integration” guide.

# Installation

To add image features to your editor, install the @ckeditor/ckeditor5-image package:

npm install --save @ckeditor/ckeditor5-image

And add the plugins that you need to your plugin list. You also need to set the image toolbar items.

import Image from '@ckeditor/ckeditor5-image/src/image';
import ImageToolbar from '@ckeditor/ckeditor5-image/src/imagetoolbar';
import ImageCaption from '@ckeditor/ckeditor5-image/src/imagecaption';
import ImageStyle from '@ckeditor/ckeditor5-image/src/imagestyle';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image, ImageToolbar, ImageCaption, ImageStyle ],
        image: {
            toolbar: [ 'imageTextAlternative', '|', 'imageStyle:full', 'imageStyle:side' ]
        }
    } )
    .then( ... )
    .catch( ... );

Read more about installing plugins.

# Common API

The Image plugin registers:

The ImageStyle plugin registers:

  • A button for each defined style — e.g. 'imageStyle:full' and 'imageStyle:side'.

  • The 'imageStyle' command which accepts a value based on the image.styles configuration option (e.g. 'full' and 'side'):

    editor.execute( 'imageStyle', { value: 'side' } );
    

The ImageUpload plugin registers:

  • The 'imageUpload' button which opens the native file browser to let you upload a file directly from your disk.
  • The 'imageUpload' command which accepts the file to upload.

# Contribute

The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-image.