CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

MediaEmbedConfig (media-embed)

@ckeditor/ckeditor5-media-embed/src/mediaembed

interface
See source

The configuration of the media embed features.

Read more about configuring the media embed feature.

ClassicEditor
	.create( editorElement, {
		mediaEmbed: ... // Media embed feature options.
	} )
	.then( ... )
	.catch( ... );

See all editor options.

Filtering

Properties

  • elementName : String

    Overrides the element name used for "semantic" data.

    See source

    This is not relevant if config.mediaEmbed.previewsInData is set to true.

    When not set, the feature produces the <oembed> tag:

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

    To override the element name with, for instance, the o-embed name:

    mediaEmbed: {
	elementName: 'o-embed'
}

    This will produce semantic data with the <o-embed> tag:

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

    Defaults to 'oembed'

  • extraProviders : Array.<MediaEmbedProvider>

    The additional media providers supported by the editor. This configuration helps extend the default providers.

    See source
    ClassicEditor
	.create( editorElement, {
		plugins: [ MediaEmbed, ... ],
		mediaEmbed: {
			extraProviders: [
				{
					 name: 'extraProvider',
					 url: /^example\.com\/media\/(\w+)/,
					 html: match => '...'
				},
				...
			]
		}
	} )
	.then( ... )
	.catch( ... );

    See the provider syntax to learn more.

  • previewsInData : Boolean

    Controls the data format produced by the feature.

    See source

    When false (default), the feature produces "semantic" data, i.e. it does not include the preview of the media, just the <oembed> tag with the url attribute:

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

    When true, the media is represented in the output in the same way it looks in the editor, i.e. the media preview is saved to the database:

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

    Note: Media without preview are always represented in the data using the "semantic" markup regardless of the value of the previewsInData. Learn more about different kinds of media in the config.mediaEmbed.providers configuration description.

    Defaults to false

  • providers : Array.<MediaEmbedProvider>

    The default media providers supported by the editor.

    See source

    The names of providers with rendering functions (previews):

    • "dailymotion",
    • "spotify",
    • "youtube",
    • "vimeo"

    The names of providers without rendering functions:

    • "instagram",
    • "twitter",
    • "googleMaps",
    • "flickr",
    • "facebook"

    See the provider syntax to learn more about different kinds of media and media providers.

    Note: The default media provider configuration may not support all possible media URLs, only the most common are included.

    Media without rendering functions are always represented in the data using the "semantic" markup. See config.mediaEmbed.previewsInData to learn more about possible data outputs.

    The priority of media providers corresponds to the order of configuration. The first provider to match the URL is always used, even if there are other providers that support a particular URL. The URL is never matched against the remaining providers.

    To discard all default media providers, simply override this configuration with your own definitions:

    ClassicEditor
	.create( editorElement, {
		plugins: [ MediaEmbed, ... ],
		mediaEmbed: {
			providers: [
				{
					 name: 'myProvider',
					 url: /^example\.com\/media\/(\w+)/,
					 html: match => '...'
				},
				...
			]
		}
	} )
	.then( ... )
	.catch( ... );

    You can take inspiration from the default configuration of this feature which you can find in: https://github.com/ckeditor/ckeditor5-media-embed/blob/master/src/mediaembedediting.js

    To extend the list of default providers, use config.mediaEmbed.extraProviders.

    To remove certain providers, use config.mediaEmbed.removeProviders.

  • removeProviders : Array.<String>

    The list of media providers that should not be used despite being available in config.mediaEmbed.providers and config.mediaEmbed.extraProviders

    See source
    mediaEmbed: {
	removeProviders: [ 'youtube', 'twitter' ]
}

  • toolbar : Array.<String>

    Items to be placed in the media embed toolbar. This option requires adding MediaEmbedToolbar to the plugin list.

    See source

    Read more about configuring toolbar in toolbar.