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. You also need to set the desired 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 ],
        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 ready-to-use editor builds provides support for both inline and block images, working as a glue for 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 (e.g., 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.