# Resizing media embeds

The media embed resize feature lets you change the width of media embeds (such as YouTube or Vimeo videos) in your content. It is implemented by the [`MediaEmbedResize`](../../api/module_media-embed_mediaembedresize-MediaEmbedResize.md) plugin.

> **Unlock this feature with selected CKEditor Plans**
>
> Try all premium features – no credit card needed.
>
> [Sign up for a free trial ](https://portal.ckeditor.com/checkout?plan=free)[Select a Plan](https://ckeditor.com/pricing/)

<a id="demo">

## Demo

Click the media embed in the editor below to select it, then drag any of its corner handles to change the width.

<!-- 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="methods-to-resize-media-embeds">

## Methods to resize media embeds

You can resize media embeds using any of the following methods:

* [Drag handles](#using-resize-handles) — click and drag the corner handles of a selected media widget.
* [Resize dropdown](#using-the-resize-dropdown) — pick a predefined size or set a custom width via a toolbar dropdown.
* [Standalone resize buttons](#using-standalone-resize-buttons) — place individual buttons for each predefined size in the media toolbar.

Both the dropdown and the standalone buttons are fully keyboard-accessible and satisfy the WCAG 2.1 keyboard navigation requirements.

<a id="using-resize-handles">

### Using resize handles

When enabled, selecting a media widget shows four corner resize handles. Dragging a handle resizes the embed proportionally while preserving its aspect ratio.

<a id="using-the-resize-dropdown">

### Using the resize dropdown

Add `'resizeMediaEmbed'` to the `mediaEmbed.toolbar` option to show a dropdown in the media embed toolbar. The dropdown contains a list of predefined sizes, a **Custom** entry that opens a balloon with a numeric input, and an **Original** entry that removes any applied resize.

```js
ClassicEditor
	.create( {
		/* ... */
		mediaEmbed: {
			toolbar: [ 'resizeMediaEmbed' ],
			resizeOptions: [
				{ name: 'resizeMediaEmbed:original', value: null,	 icon: 'original' },
				{ name: 'resizeMediaEmbed:custom',   value: 'custom', icon: 'custom'   },
				{ name: 'resizeMediaEmbed:25',	   value: '25',	 icon: 'small'	},
				{ name: 'resizeMediaEmbed:50',	   value: '50',	 icon: 'medium'   },
				{ name: 'resizeMediaEmbed:75',	   value: '75',	 icon: 'large'	}
			]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

<a id="using-standalone-resize-buttons">

### Using standalone resize buttons

You can also place individual resize buttons in the toolbar instead of using a dropdown. Each button corresponds to one resize option and can be identified by a `'resizeMediaEmbed:<value>'` name.

```js
ClassicEditor
	.create( {
		/* ... */
		mediaEmbed: {
			toolbar: [
				'resizeMediaEmbed:25',
				'resizeMediaEmbed:50',
				'resizeMediaEmbed:75',
				'resizeMediaEmbed:original',
				'resizeMediaEmbed:custom'
			],
			resizeOptions: [
				{ name: 'resizeMediaEmbed:original', value: null,	 icon: 'original' },
				{ name: 'resizeMediaEmbed:custom',   value: 'custom', icon: 'custom'   },
				{ name: 'resizeMediaEmbed:25',	   value: '25',	 icon: 'small'	},
				{ name: 'resizeMediaEmbed:50',	   value: '50',	 icon: 'medium'   },
				{ name: 'resizeMediaEmbed:75',	   value: '75',	 icon: 'large'	}
			]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

<a id="disabling-resize-handles">

## Disabling resize handles

You can load `MediaEmbedResizeEditing`, `MediaEmbedResizeButtons`, and `MediaEmbedCustomResizeUI` without `MediaEmbedResizeHandles` to get a keyboard-only resize setup:

**NPM**

```js
import {
	ClassicEditor,
	MediaEmbed,
	MediaEmbedToolbar,
	MediaEmbedResizeEditing,
	MediaEmbedResizeButtons,
	MediaEmbedCustomResizeUI
} from 'ckeditor5';

ClassicEditor
	.create( {
		attachTo: document.querySelector( '#editor' ),
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ MediaEmbed, MediaEmbedToolbar, MediaEmbedResizeEditing, MediaEmbedResizeButtons, MediaEmbedCustomResizeUI, /* ... */ ],
		toolbar: [ 'mediaEmbed', /* ... */ ],
		mediaEmbed: {
			toolbar: [ 'resizeMediaEmbed' ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const {
	ClassicEditor,
	MediaEmbed,
	MediaEmbedToolbar,
	MediaEmbedResizeEditing,
	MediaEmbedResizeButtons,
	MediaEmbedCustomResizeUI
} = CKEDITOR;

ClassicEditor
	.create( {
		attachTo: document.querySelector( '#editor' ),
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ MediaEmbed, MediaEmbedToolbar, MediaEmbedResizeEditing, MediaEmbedResizeButtons, MediaEmbedCustomResizeUI, /* ... */ ],
		toolbar: [ 'mediaEmbed', /* ... */ ],
		mediaEmbed: {
			toolbar: [ 'resizeMediaEmbed' ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

This setup also needs [`MediaEmbedToolbar`](../../api/module_media-embed_mediaembedtoolbar-MediaEmbedToolbar.md), which is not loaded by [`MediaEmbed`](../../api/module_media-embed_mediaembed-MediaEmbed.md) either. It renders the `'resizeMediaEmbed'` entry from `config.mediaEmbed.toolbar` in the media widget toolbar.

<a id="markup-and-styling">

## Markup and styling

When a media embed is resized, the editor adds a `media_resized` class and an inline `width` style to the `<figure>` element (regardless of the `previewsInData` setting):

```html
<figure class="media media_resized" style="width:50%;">...</figure>
```

<a id="using-pixel-values-instead-of-percentage-width">

## Using pixel values instead of percentage width

By default, the resize values are expressed as percentages. To use pixel values instead, set `mediaEmbed.resizeUnit` to `'px'` and adjust the `resizeOptions` accordingly:

```js
ClassicEditor
	.create( {
		/* ... */
		mediaEmbed: {
			resizeUnit: 'px',
			resizeOptions: [
				{ name: 'resizeMediaEmbed:original', value: null,  icon: 'original' },
				{ name: 'resizeMediaEmbed:custom',   value: 'custom', icon: 'custom' },
				{ name: 'resizeMediaEmbed:200',	  value: '200', icon: 'small'	},
				{ name: 'resizeMediaEmbed:400',	  value: '400', icon: 'medium'   },
				{ name: 'resizeMediaEmbed:600',	  value: '600', icon: 'large'	}
			],
			toolbar: [ 'resizeMediaEmbed' ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

<a id="installation">

## Installation

The [`MediaEmbedResize`](../../api/module_media-embed_mediaembedresize-MediaEmbedResize.md) plugin is not loaded by default. Add it explicitly alongside [`MediaEmbed`](../../api/module_media-embed_mediaembed-MediaEmbed.md) to enable the feature. The `MediaEmbedResize` glue plugin loads all four sub-plugins automatically:

**NPM**

```js
import { ClassicEditor, MediaEmbed, MediaEmbedToolbar, MediaEmbedResize } from 'ckeditor5';

ClassicEditor
	.create( {
		attachTo: document.querySelector( '#editor' ),
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ MediaEmbed, MediaEmbedToolbar, MediaEmbedResize, /* ... */ ],
		toolbar: [ 'mediaEmbed', /* ... */ ],
		mediaEmbed: {
			toolbar: [ 'resizeMediaEmbed' ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const { ClassicEditor, MediaEmbed, MediaEmbedToolbar, MediaEmbedResize } = CKEDITOR;

ClassicEditor
	.create( {
		attachTo: document.querySelector( '#editor' ),
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ MediaEmbed, MediaEmbedToolbar, MediaEmbedResize, /* ... */ ],
		toolbar: [ 'mediaEmbed', /* ... */ ],
		mediaEmbed: {
			toolbar: [ 'resizeMediaEmbed' ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

Similarly, [`MediaEmbed`](../../api/module_media-embed_mediaembed-MediaEmbed.md) doesn’t load [`MediaEmbedToolbar`](../../api/module_media-embed_mediaembedtoolbar-MediaEmbedToolbar.md) by default. Add `MediaEmbedToolbar` to your `plugins` list, otherwise the entries you put in `config.mediaEmbed.toolbar` never reach the media widget toolbar.

<a id="common-api">

## Common API

The [`MediaEmbedResize`](../../api/module_media-embed_mediaembedresize-MediaEmbedResize.md) plugin registers:

* [`MediaEmbedResizeButtons`](../../api/module_media-embed_mediaembedresize_mediaembedresizebuttons-MediaEmbedResizeButtons.md) — the toolbar buttons and dropdown plugin.

* [`MediaEmbedCustomResizeUI`](../../api/module_media-embed_mediaembedresize_mediaembedcustomresizeui-MediaEmbedCustomResizeUI.md) — the balloon with the custom-width input.

* the `'resizeMediaEmbed'` dropdown component registered in the component factory.

* standalone `'resizeMediaEmbed:<value>'` button components (one for each entry in `config.mediaEmbed.resizeOptions`).

* the `'resizeMediaEmbed'` command implemented by [`ResizeMediaEmbedCommand`](../../api/module_media-embed_mediaembedresize_resizemediaembedcommand-ResizeMediaEmbedCommand.md).

  You can resize the selected media embed or remove a previously-applied resize by executing the following code:

  ```js
  // Resize the selected media to 50% width.
  editor.execute( 'resizeMediaEmbed', { width: '50%' } );

  // Remove the width to return to the default size.
  editor.execute( 'resizeMediaEmbed', { width: null } );
  ```

> **Note**
>
> We recommend using the official [CKEditor 5 inspector](../../framework/development-tools/inspector.md) for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

<a id="contribute">

## Contribute

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

---

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