Embedding media with CKEditor 5

This page explains how to set up a text editor so that it can access the media library and use it to embed media in your content. If you have not already installed Media and Media Library core modules, see the Overview page for instructions.

To make the media library available to a text editor, you must configure the text format associated with the editor. See the Filter module documentation for more information on text formats and how to configure them.

Setting up media embedding in CKEditor 5

Drag the Media Library button into your CKEditor toolbar

In a text format that uses CKEditor 5, you should see this button for the media library, under "Available buttons" in the "Toolbar configuration" section of the page:Drag the media library button from the "Available buttons" section to "Active Toolbar"

Enable the "Embed media" filter

The button is present, and this step then allows media to be embedded in the editor:

It is recommended to place the "Embed media" filter as the final item in the filter list, as there are several filters that (if enabled),  must run prior to it such as "Limit allowed HTML tags and correct faulty HTML", "Align images" and "Caption images".

If you have the "Limit allowed HTML tags and correct faulty HTML" filter enabled, the following will be automatically added to the "Allowed HTML tags" field/

<drupal-media data-entity-type data-entity-uuid data-view-mode data-align data-caption alt>

Additional settings

Optionally, you can tweak a few additional settings for the "Embed media" filter:

1. Default view mode: This indicates the view mode configuration of the inserted media item, in other words, the way the media will be displayed on the front end.
2. Media types selectable in the Media Library: This allows you to only offer certain media types in the Media Library selection interface.
3. View modes selectable in the 'Edit media' dialog: These selections will create a drop-down field in the "Edit media" modal dialog (see second image below) and determine which view modes are available as select options. But in order for this to work, you have to check the "Allow the user to override the default view mode" checkbox under CKEditor 5 plugin settings - Media for your text format.

Configuring media embed in "Basic HTML" text format in Umami core installation profile.

Selecting view mode in Umami core installation profile.

Embedding media in CKEditor 5

When using a CKEditor 5 editor configured to embed media, clicking the Media Library button will expose the media library in a modal.

When using media library with CKEditor 5 note that, you can only select (or add) one item at a time.

Any media item you've embedded will appear in the editor as a live preview:

In some instances, the live preview within the editor will not 100% match how the media is displayed on the final page.

You may edit each media item by clicking the item and choosing an option in the balloon toolbar that appears. Here, there will be options such as overriding alt text, image alignment options, and captions. The specific options available are determined by the media type and the text format's media configuration

Adding a caption

Customizing the Edit Embedded Media form

Please note: this technique is not officially supported by Drupal core. It may break in minor releases.

If you need to add extra fields to the Edit form, such as manually entered classes; options to hide on mobile; and so forth, you can do this in the following way.

First, implement hook_form_FORM_ID_alter() for the editor_media_dialog form in a custom module or theme.  Here's an example of adding a text field to allow extra CSS classes and an extra data-attribute option to the rendered output.

use Drupal\Core\Form\FormStateInterface;

/**
 * Implements hook_form_FORM_ID_alter().
 */
function MY_MODULE_form_editor_media_dialog_alter(array &$form, FormStateInterface $form_state) {
  if (isset($form_state->getUserInput()['editor_object'])) {
    $editor_object = $form_state->getUserInput()['editor_object'];
    $media_embed_element = $editor_object['attributes'];
  } else {
    // Retrieve the user input from form state.
    $media_embed_element = $form_state->get('media_embed_element');
  }

  $form['extra_classes'] = [
    '#title' => t('Extra Classes'),
    '#type' => 'textfield',
    '#step' => '1',
    '#default_value' => empty($media_embed_element['class']) ? '' : $media_embed_element['class'],
    '#parents' => ['attributes', 'class'],
  ];
  $form['data-my-data'] = [
    '#title' => t('Extra Data Attribute'),
    '#type' => 'textfield',
    '#step' => '1',
    '#default_value' => empty($media_embed_element['data-my-data']) ? '' : $media_embed_element['data-my-data'],
    '#parents' => ['attributes', 'data-my-data'],
  ];
}

After enabling your new module and clearing all caches, you should see two new fields in the Edit Media dialog box.

Note the #parents property. This ensures that the extra attributes will be added to the drupal-media tag, e.g.:

<drupal-media class="MY-EXTRA-CLASS MY-EXTRA-CLASS2" data-align="right" data-entity-type="media" data-entity-uuid="f060a7bd-a588-43c6-84d4-be7c1ff0167d" data-my-data="MY-VALUE-HERE"></drupal-media>

Make sure to add any extra attributes to the relevant format, so that they won't be removed by the HTML filter. You can do this in the same way you need to add the standard extra attributes for embedded media.

These extra attributes will be added to the Attributes object when the embedded media is rendered. They can be retrieved from the Attributes object during processing.

Some examples of this are:

The class attribute: you probably don't need any more code. Normally this gets passed along to the standard template for embedded media.

The data-my-data attribute, you can deal with in either the appropriate preprocess function, or directly in the relevant Twig template (e.g. media--image.html.twig), like:

{% if attributes['data-my-data'] %}
  {# do stuff #}
{% endif %}