Installation

The vast majority of image-related features are available in all predefined builds and require no additional installation. If you want to change the default configuration or create a custom editor build, you can enable image-related features by installing the @ckeditor/ckeditor5-image package:

npm install --save @ckeditor/ckeditor5-image

Next, add the plugins that you need to your plugin list and to the editor toolbar.

import { Image, ImageCaption, ImageResize, ImageStyle, ImageToolbar } from '@ckeditor/ckeditor5-image';
import { LinkImage } from '@ckeditor/ckeditor5-link';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image, ImageToolbar, ImageCaption, ImageStyle, ImageResize, LinkImage ],
        toolbar: [ 'insertImage', /* ... */ ],
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 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:

import { Image } from '@ckeditor/ckeditor5-image';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image ],
        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:

import { Image } from '@ckeditor/ckeditor5-image';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image ],
        toolbar: [ 'insertImage', /* ... */ ],
        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( /* ... */ );

# Configuring the contextual image toolbar

You also need to configure the desired contextual image toolbar items. Notice the separators used to organize the toolbar.

import { Image, ImageCaption, ImageResize, ImageStyle, ImageToolbar } from '@ckeditor/ckeditor5-image';
import { LinkImage } from '@ckeditor/ckeditor5-link';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image, ImageToolbar, ImageCaption, ImageStyle, ImageResize, LinkImage ],
        toolbar: [ 'insertImage', /* ... */ ],
        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( /* ... */ );

# 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 plugin available in all predefined editor builds supports both inline and block images, working as a glue for the ImageInline and ImageBlock 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.

If you wish to modify this behavior, the type setting in the editor configuration can be used:

ClassicEditor.create( element, {
    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.

# Contribute

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