Media embed

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

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. Try both approaches with the following URLs:

After installing the editor, add the feature to your plugin list and toolbar configuration:

import { ClassicEditor, MediaEmbed } from 'ckeditor5';

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

const { ClassicEditor, MediaEmbed } = CKEDITOR;

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

The @ckeditor/ckeditor5-media-embed package contains multiple plugins that implement media-related features:

• Configuration – set the data output format and extend, remove, or override the default media providers.
• External services – use Iframely or Embedly to render rich previews inside the editor and on your target website.
• Resizing media embeds – enable drag-to-resize handles for media widgets (premium).
• Media embed styles – alignment and other configurable styles applied to the media <figure> (alignment built-ins, customizable per integrator).
• Styling non-previewable media – create dedicated styles for specific non-previewable media providers.

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.

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:

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

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

Also, the media embed feature does not support asynchronous preview providers 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 above).
2. Produce a semantic <oembed url="..."> tag 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.

You can overcome these limitations with the help of proxy services like Iframely or Embedly. See Using external services for media previews.

By default, the MediaEmbed plugin loads the AutoMediaEmbed as a dependency.

The AutoMediaEmbed 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.

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

The MediaEmbed plugin registers:

• the 'mediaEmbed' UI button component,

• the 'mediaEmbed' command implemented by MediaEmbedCommand.

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

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

  Copy code

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