# Media embed

<!-- 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. -->

The media embed feature lets you insert embeddable media such as YouTube or Vimeo videos and tweets into your rich text content.

<a id="demo">

## Demo

You can use the insert media button in the toolbar to embed media. You can also paste a media URL directly into the editor content, and it will be [automatically embedded](#automatic-media-embed-on-paste). Try both approaches with the following URLs:

*
*
*

<!-- 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="installation">

## Installation

After [installing the editor](../../getting-started/installation/cloud/quick-start.md), add the feature to your plugin list and toolbar configuration:

**NPM**

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

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ MediaEmbed, /* ... */ ],
		toolbar: [ 'mediaEmbed', /* ... */ ],
		mediaEmbed: {
			// Configuration.
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

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

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ MediaEmbed, /* ... */ ],
		toolbar: [ 'mediaEmbed', /* ... */ ],
		mediaEmbed: {
			// Configuration.
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

> **Note**
>
> Depending on how you will configure this feature, you may need to use services like [Iframely](https://iframely.com/) or [Embedly](https://embed.ly/) to display content of embedded media on your target website. Read more about [displaying embedded media](media-embed-external-preview.md).

<a id="media-embed-features">

## Media embed features

The [`@ckeditor/ckeditor5-media-embed`](https://www.npmjs.com/package/@ckeditor/ckeditor5-media-embed) package contains multiple plugins that implement media-related features:

* [Configuration](media-embed-configuration.md) – set the data output format and extend, remove, or override the default media providers.
* [External services](media-embed-external-preview.md) – use Iframely or Embedly to render rich previews inside the editor and on your target website.
* [Resizing media embeds](media-embed-resize.md) – enable drag handles, a toolbar dropdown, or standalone buttons for predefined sizes plus a custom-width balloon for media widgets (premium).
* [Media embed styles](media-embed-styles.md) – alignment and other configurable styles applied to the media `<figure>` (alignment built-ins, customizable per integrator).
* [Styling non-previewable media](styling-non-previewable-media.md) – create dedicated styles for specific non-previewable media providers.

<a id="previewable-and-non-previewable-media">

## Previewable and non-previewable media

When the media embed feature is asked to embed a specific media element via its URL, it needs to decide about how the media will be displayed in the editor.

<a id="previewable-media">

### Previewable media

If, for instance, the URL to embed is `https://www.youtube.com/watch?v=H08tGjXNHO4`, the feature can predict that it needs to produce the following HTML to show this YouTube video:

```html
<div>
	<iframe src="https://www.youtube.com/embed/${ videoId }"
		width="1280" height="720"
		style="width: 100%; height: auto; aspect-ratio: 16 / 9; border: 0; display: block;"
		frameborder="0" allow="autoplay; encrypted-media" allowfullscreen>
	</iframe>
</div>
```

The CSS `aspect-ratio` property keeps the video responsive, while the HTML `width` and `height` attributes provide an intrinsic size so the iframe behaves well in table cells and other layout contexts. The crucial part is the iframe element’s `src` which the media embed feature predicts based on the given video URL.

Thanks to the ability to hardcode this URL to HTML transformation, the media embed feature can show previews of YouTube, Dailymotion, or Vimeo videos, and Spotify widgets without requesting any external service.

<a id="non-previewable-media">

### Non-previewable media

Unfortunately, to show previews of media such as tweets, Instagram photos, or Facebook posts, the editor would need to retrieve the content of these from an external service. Some of these media providers expose [oEmbed endpoints](https://oembed.com/) but not all. These endpoint responses often require further processing to be embeddable. Most importantly, though, the media embed feature is often not able to request these services due to the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy).

Also, the media embed feature [does not support asynchronous preview providers](https://github.com/ckeditor/ckeditor5-media-embed/issues/16) yet. Therefore, to still allow embedding tweets or Instagram photos, we chose to:

1. Show a placeholder of the embedded media in the editor (see how a tweet is presented in the [demo](#demo) above).
2. Produce a [semantic `<oembed url="...">` tag](media-embed-configuration.md#semantic-data-output-default) in the data output from the editor. This output makes it possible to later use proxy services to [display the content of these media on your website](media-embed-external-preview.md).

You can overcome these limitations with the help of proxy services like Iframely or Embedly. See [Using external services for media previews](media-embed-external-preview.md).

<a id="automatic-media-embed-on-paste">

## Automatic media embed on paste

By default, the [`MediaEmbed`](../../api/module_media-embed_mediaembed-MediaEmbed.md) plugin loads the [`AutoMediaEmbed`](../../api/module_media-embed_automediaembed-AutoMediaEmbed.md) as a dependency.

The [`AutoMediaEmbed`](../../api/module_media-embed_automediaembed-AutoMediaEmbed.md) plugin recognizes media links in the pasted content and embeds them shortly after they are injected into the document to speed up the editing. Just like the “traditional” embedding (using the toolbar button), automatic embedding works for all media providers specified in the [configuration](media-embed-configuration.md#media-providers).

> **Note**
>
> The media URL must be the only content pasted to be properly embedded. Multiple links (`"http://media.url http://another.media.url"`) as well as bigger chunks of content (`"This link http://media.url will not be auto–embedded when pasted."`) are ignored.

If the automatic embedding was unexpected, for instance when the link was meant to remain in the content as text, undo the action (by clicking the “Undo” button in the toolbar or using the `Ctrl`/`Cmd`+`Z` keystrokes).

<a id="common-api">

## Common API

The [`MediaEmbed`](../../api/module_media-embed_mediaembed-MediaEmbed.md) plugin registers:

* the `'mediaEmbed'` UI button component,

* the `'mediaEmbed'` command implemented by [`MediaEmbedCommand`](../../api/module_media-embed_mediaembedcommand-MediaEmbedCommand.md).

  You can insert a new media element or update the selected media URL by executing the following code:

  ```js
  editor.execute( 'mediaEmbed', 'http://url.to.the/media' );
  ```

> **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)