Contribute to this guideReport an issue

guideEasy Image integration

CKEditor 5 introduces a new way of handling images, with a strong focus on the end–user experience. This feature is called Easy Image and its goal is to make the image upload as effortless and intuitive as possible.

This feature is enabled by default in all builds.

Easy Image is part of the CKEditor Cloud Services offer. It is a SaaS product which:

  • securely uploads images,
  • takes care of rescaling and optimizing them as well as providing various image sizes (responsive images),
  • delivers uploaded images through a blazing-fast CDN.

All that with virtually zero server setup.

Check out the comprehensive Image upload overview to learn about other ways to upload images in CKEditor 5.

# Demo

The demo below uses the Classic editor configured to use the Easy Image service provided by CKEditor Cloud Services:

Paste or drop an image directly into the editor. You can also use the "Insert image" button in the toolbar.

# Configuration

To make enabling image upload in CKEditor 5 a breeze, by default all builds include the EasyImage plugin. It integrates with the Easy Image service provided by CKEditor Cloud Services. Enabling it is straightforward and the results are immediate:

  1. Follow the Easy Image — Quick start guide to set up an account.

  2. Configure CKEditor 5 (see CloudServicesConfig):

        .create( document.querySelector( '#editor' ), {
            cloudServices: {
                tokenUrl: '',
                uploadUrl: ''
        } )
        .then( ... )
        .catch( ... );

This is all. At this point, image upload will be automatically enabled in your application.

If you are having troubles with setting up Easy Image, please contact us.

# Responsive images

Another great feature introduced with CKEditor 5 is the ability to have responsive images in the rich-text editor content. With a single image upload, several optimized versions of that image are created, each for a different size of the display. All this is transparent to the end user who uploaded the image.

The visualization of the responsive images approach for CKEditor 5 WYSIWYG editor.

# Why responsive images?

Responsive images have two main advantages over the “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 Easy Image 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 — see it yourself!

  • 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 ages for high–resolution photos to load on a tiny smartphone screen.

# Responsive images in the markup

Responsive images delivered by the Easy Image service are transparent to your application. Once uploaded, the image appears in the editor content as a “regular” image but with some additional attributes like the srcset.

The srcset attribute specifies the image variants dedicated for the various screen sizes for the web browser to choose from (360px, 720px, 1080px, 1440px, etc.). For instance the image.jpg file uploaded by the user will have the following markup:

<figure class="image">
        srcset=" 360w,

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. See the detailed Easy Image service documentation to learn more about responsive images and other features offered by the service.

# What’s next?

Check out the comprehensive Image upload overview to learn more about different ways of uploading images in CKEditor 5.

See the Image feature guide to find out more about handling images in CKEditor 5.

# Installation

This feature is enabled by default in all builds. The installation instructions are for developers interested in building their own, custom WYSIWYG editor.

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

npm install --save @ckeditor/ckeditor5-easy-image

Then add EasyImage to your plugin list and configure the feature. For instance:

import EasyImage from '@ckeditor/ckeditor5-easy-image/src/easyimage';

    .create( document.querySelector( '#editor' ), {
        plugins: [ EasyImage, ... ],
        toolbar: [ 'imageUpload' ... ], // Depending on your preference.
        cloudServices: // feature configuration
    } )
    .then( ... )
    .catch( ... );