# Images in CKEditor 5 (overview)

CKEditor 5 comes with various tools to insert, upload, resize, style, caption, and link images. All these features work out of the box with block, inline, and responsive images alike.

<a id="demo">

## Demo

To see all the image features in action, check out the demo below. To learn more about individual plugins (sub-features) of the image ecosystem, see the [**Image features**](#image-features) section.

<!-- AI-AGENT-NOTE: An interactive demo is embedded here but is not represented in this Markdown file. If you need to see it in action, open this page in a browser (e.g. via a browser-automation MCP like Chrome DevTools or Playwright), or let the user know a live demo is available on this page. -->

This demo presents a limited set of features. Visit the [feature-rich editor example](../../examples/builds-custom/full-featured-editor.md) to see more in action.

<a id="base-image-feature">

## Base image feature

The base image feature does not support any user interface for inserting or managing images. Its sole purpose is to lay ground for other plugins (listed below) 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.

<a id="image-features">

## Image features

The [`@ckeditor/ckeditor5-image`](https://www.npmjs.com/package/@ckeditor/ckeditor5-image) package contains multiple plugins that implement various image-related features. The [`Image`](../../api/module_image_image-Image.md) plugin is at the core of the ecosystem. It provides the basic support for block and inline images. There are many other features that extend the editor’s capabilities:

* The [contextual toolbar](#image-contextual-toolbar) available on mouse click gives access to image features.
* [Image captions](images-captions.md) allow adding descriptive text under the image.
* The [image styles](images-styles.md) help control the placement, size, and other characteristics with predefined styles.
* The [text alternative](images-text-alternative.md) tag aids accessibility and SEO, provides additional image description, and supports better navigation.
* [Image resizing](images-resizing.md) lets the user control the dimensions of images in the content.
* [Linking images](images-linking.md) makes it possible to use them as URL anchors.
* A selection of [image upload methods](image-upload/image-upload.md) allows for the most convenient way of adding images. These include support for [inserting an image via a URL](images-inserting.md#inserting-images-via-pasting-a-url-into-the-editor) and even [via pasting a URL into the editor](images-inserting.md#inserting-images-via-a-source-url) along with custom integrations.
* The [CKBox](../file-management/ckbox.md) and Uploadcare [features/uploadcare](../file-management/uploadcare.md) management platforms provide support for [responsive images](images-responsive.md) in CKEditor 5. Responsive images will display correctly on any viewport, enhancing the accessibility, reach, and user experience.
* Both Uploadcare and CKBox provide [editing and optimization capabilities](images-image-optimizer.md), like cropping, resizing, rotating, and flipping right from the image contextual toolbar.

<a id="image-contextual-toolbar">

## Image contextual toolbar

The [`ImageToolbar`](../../api/module_image_imagetoolbar-ImageToolbar.md) 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](images-text-alternative.md) button, the [image caption](images-captions.md) button, and [image styles](images-styles.md) buttons. The toolbar can also host the image editing button introduced by the [CKBox asset manager](../file-management/ckbox.md). Shown below is an example contextual toolbar with an extended set of buttons.

The image toolbar is configurable using the [`config.image.toolbar`](../../api/module_image_imageconfig-ImageConfig.md#member-styles) property. For instance, to display the caption toggle, text alternative and editing buttons, use the following configuration:

```js
ClassicEditor
	.create( {
		image: {
			toolbar: [ 'toggleImageCaption', 'imageTextAlternative', 'ckboxImageEdit' ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

Refer to the [image installation](images-installation.md) guide for more details on configuring the features available in the toolbar and to the `#image-toolbar` section of the `Update to 29.x` guide in the [updating from older versions guide](../../updating/guides/updating-from-older-versions.md), as important changes were introduced in that version. You can also check the [editor toolbar](../../getting-started/setup/toolbar.md) guide.

See the common API of image-related features such as [`ImageStyle`](../../api/module_image_imagestyle-ImageStyle.md), [`ImageResize`](../../api/module_image_imageresize-ImageResize.md), and [`LinkImage`](../../api/module_link_linkimage-LinkImage.md) to learn more about available image toolbar buttons.

<a id="image-width-and-height-attributes">

## Image `width` and `height` attributes

Starting with v40.0.0, the image’s `width` and `height` attributes are retained by the editor when it is loaded. Adding them is done to ensure that the image dimensions ratio is properly kept when an image is styled or aligned and that it always looks like it should, rather than forcing the image size within the content. This ensures high-quality output.

The attributes are now handled as follows:

* Upon [uploading an image file](image-upload/image-upload.md) or [inserting it](images-inserting.md) into the editor content, the CKEditor 5 image feature fetches these dimensions from the file. The editor then adds these properties to the markup, just like the [text alternative tag](images-text-alternative.md).
* If the user uses an upload adapter and the server sends back the uploaded image with the `width` or `height` parameters already set, these existing values are not overwritten.
* The editor will not change already existing content. It means, loading HTML (that is `setData`) with images does not set up these attributes.
* Changes to an image (such as resize, etc.) will trigger the creation of those attributes. These attributes are crucial to proper content handling, and actions on a current image that does not have these improve this image’s markup.
* The `aspect-ratio` attribute has been added to the image’s properties to handle situations when the file is resized or scaled with a tweaked aspect ratio.

These image properties can be further controlled via CSS styles. If you need to crop, resize, rotate, or mirror flip your images, you can use the [CKBox asset manager](../file-management/ckbox.md) to achieve that.

> **Note**
>
> Due to the introduction of this new behavior in CKEditor 5 v40.0.0, the `width` and `height` attributes are now used to preserve the image’s natural width and height. The information about a resized image is stored in the `resizedWidth` and `resizeHeight` attributes.

<a id="typing-around-images">

## Typing around images

To type before or after an image easily, select the image, then press the Arrow key (`←` or `→`) once, depending on where you want to add content – before or after respectively. The image becomes no longer selected and whatever text you type will appear in the desired position.

You can also use the **Insert paragraph** handles on the bottom or top edge of the selected image to add a paragraph below or above the image, respectively.

<a id="image-editing">

## Image editing

While the image feature does not provide native image editing support, the [CKBox](../file-management/ckbox.md) and Uploadcare [features/uploadcare](../file-management/uploadcare.md) premium features provide [editing capabilities](images-image-optimizer.md) such as cropping to presets, flipping, or rotating.

<a id="common-api">

## Common API

The `Image` plugin registers:

* The [`insertImage`](../../api/module_image_image_insertimagecommand-InsertImageCommand.md) command (alias: `imageInsert`).
* The [`insertImage`](../../api/module_image_imageconfig-ImageInsertConfig.md) dropdown component (to use in the toolbar).

> **Note**
>
> The basic image plugin is minimal and provides the foundation for the image ecosystem. Subplugins register most UI components (buttons, toolbars) and additional commands. See the feature guides linked in the [Image features](#image-features) section for more information about their APIs.

<a id="contribute">

## Contribute

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

---

Full index of the CKEditor 5 documentation: [llms.txt](../../../llms.txt)