# Media embed configuration

You can configure the data output format and the list of supported media providers used by the [`MediaEmbed`](../../api/module_media-embed_mediaembed-MediaEmbed.md) plugin.

<a id="data-output-format">

## Data output format

You can configure the data output format of the feature using the [`config.mediaEmbed.previewsInData`](../../api/module_media-embed_mediaembedconfig-MediaEmbedConfig.md#member-previewsInData) option.

> **Note**
>
> This option does not change how the media are displayed inside the editor. The previewable ones will still be displayed with previews. It only affects the output data (see below).

<a id="semantic-data-output-default">

### Semantic data output (default)

By default, the media embed feature outputs semantic `<oembed url="...">` tags for previewable and non-previewable media. That being so, it works best when the application processes (expands) the media on the server side or [directly in the frontend](media-embed-external-preview.md), preserving the versatile database representation:

```html
<figure class="media">
	<oembed url="https://media-url"></oembed>
</figure>
```

You can achieve further customization of the semantic data output through the [`config.mediaEmbed.elementName`](../../api/module_media-embed_mediaembedconfig-MediaEmbedConfig.md#member-elementName) configuration. As an example, if you set `elementName` to `o-embed`:

```html
<figure class="media">
	<o-embed url="https://media-url"></o-embed>
</figure>
```

If `elementName` is overridden to something other than the default value, the existing `<oembed>` elements will still be shown for backward compatibility purposes.

<a id="including-previews-in-data">

### Including previews in data

Optionally, by setting `mediaEmbed.previewsInData` to `true` you can configure the media embed feature to output media in the same way they look in the editor. If the media element is “previewable,” the media preview (HTML) is saved to the database:

```html
<figure class="media">
	<div data-oembed-url="https://media-url">
		<iframe src="https://media-preview-url"></iframe>
	</div>
</figure>
```

Currently, the preview is only available for content providers for which CKEditor 5 can predict the `<iframe>` code: YouTube, Vimeo, Dailymotion, Spotify, etc. For other providers like X (Twitter) or Instagram, the editor cannot produce an `<iframe>` code. It also does not allow retrieving this code from an external oEmbed service. Therefore, for non-previewable media, it produces the default semantic output:

```html
<figure class="media">
	<oembed url="https://media-url"></oembed>
</figure>
```

This means that, unless you [limit the list of providers](#media-providers) to only those that are previewable, you need to [make sure that the media are displayed on your website](media-embed-external-preview.md).

Read more about [non-previewable media](media-embed.md#previewable-and-non-previewable-media).

<a id="media-providers">

## Media providers

CKEditor 5 comes with several supported media providers that you can extend or alter.

Names of providers **with previews**:

* `'dailymotion'`,
* `'spotify'`,
* `'youtube'`,
* `'vimeo'`.

Names of providers **without previews**:

* `'instagram'`,
* `'twitter'`,
* `'googleMaps'`,
* `'flickr'`,
* `'facebook'`.

> **Note**
>
> The default media provider configuration does not support all possible media URLs – only the most common are included. Services like Iframely or Embedly support thousands of media providers. It is up to you to define which you want to allow.

<a id="extending-media-providers">

### Extending media providers

To extend the default list of providers, use [`config.mediaEmbed.extraProviders`](../../api/module_media-embed_mediaembedconfig-MediaEmbedConfig.md#member-extraProviders).

<a id="removing-media-providers">

### Removing media providers

To remove certain providers, use [`config.mediaEmbed.removeProviders`](../../api/module_media-embed_mediaembedconfig-MediaEmbedConfig.md#member-removeProviders).

For instance, to leave only the previewable providers, configure this feature as follows:

```js
ClassicEditor
	.create( {
		// ... Other configuration options ...
		mediaEmbed: {
			removeProviders: [ 'instagram', 'twitter', 'googleMaps', 'flickr', 'facebook' ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

<a id="overriding-media-providers">

### Overriding media providers

To override the default providers, use [`config.mediaEmbed.providers`](../../api/module_media-embed_mediaembedconfig-MediaEmbedConfig.md#member-providers) and define your set according to the [provider syntax](../../api/module_media-embed_mediaembedconfig-MediaEmbedProvider.md):

```js
ClassicEditor
	.create( {
		// ... Other configuration options ...
		mediaEmbed: {
			providers: [
				{
					// A URL regular expression or an array of URL regular expressions:
					url: /^example\.com\/media\/(\w+)/,

					// To be defined only if the media are previewable:
					html: match => '...'
				},
				// More providers.
				// ...
			]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

You can take inspiration from the default configuration of this feature. You can find it in <https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-media-embed/src/mediaembedediting.ts>

---

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