Entity Embed
Allows any entity to be embedded within text content using CKEditor and configurable display options.
entity_embed
Install
composer require 'drupal/entity_embed:8.x-1.7'
composer require 'drupal/entity_embed:8.x-1.6'
Overview
Entity Embed is a powerful Drupal module that enables content editors to embed any entity (nodes, media, files, users, taxonomy terms, etc.) directly into text content using the CKEditor WYSIWYG editor. The module extends Drupal's text filtering system to recognize and render embedded entities within formatted text fields.
The module provides a flexible plugin system for controlling how embedded entities are displayed, supporting various field formatters and view modes. It integrates seamlessly with Drupal's Filter and Editor systems, allowing administrators to configure which entities can be embedded and how they appear in content.
Entity Embed supports both CKEditor 4 (deprecated) and CKEditor 5, provides Entity Browser integration for enhanced entity selection, and includes comprehensive hook APIs for customization. The module handles entity translations, alignment options, captions, and recursive rendering protection.
Features
- Embed any Drupal entity (nodes, media, files, users, taxonomy terms, etc.) within rich text content using CKEditor
- Support for CKEditor 5 with dedicated toolbar buttons for each embed button configured
- Multiple display plugin system allowing entities to be rendered using field formatters or view modes
- Entity Browser integration for visual entity selection instead of autocomplete
- Alignment support (left, center, right) when used with Drupal's filter_align filter
- Caption support for embedded entities when used with Drupal's filter_caption filter
- Translation-aware embedding with language code tracking via data-langcode attribute
- Configurable bundle restrictions to limit which content types can be embedded
- Per-button display plugin restrictions to control available display options
- Media image alt and title text override capability for accessibility
- Recursive rendering protection with configurable depth limit (default 20)
- Twig extension providing entity_embed() function for programmatic embedding in templates
- Comprehensive hook API for altering display plugins, context, and build output
- Automatic migration of legacy data-view-mode attribute to new display plugin format
Use Cases
Embedding media in body content
Content editors can embed media entities (images, videos, documents) directly in the body field of articles. Click the entity embed button in CKEditor, search for and select a media item, choose a display format (thumbnail, full, etc.), optionally add alignment and caption, then embed. The media renders inline with the text content.
Referencing related content inline
Embed references to other nodes within body content to create rich, interconnected content. For example, embed a product node within a blog post with teaser display to show product details inline without leaving the article.
Building reusable content blocks
Create block content entities for common content snippets (callouts, author bios, promotional banners) and embed them in multiple pages. Changes to the block entity automatically reflect everywhere it's embedded.
Custom entity embedding
Embed custom entities (events, locations, team members) created by contrib or custom modules. Configure an embed button for the custom entity type and select appropriate view modes for display.
Visual entity selection with Entity Browser
Configure embed buttons to use Entity Browser for a visual, gallery-style selection interface instead of autocomplete. Useful for media-heavy sites where editors need to browse and preview content before selection.
Programmatic embedding in templates
Use the entity_embed() Twig function to embed entities in templates without editor interaction: {{ entity_embed('node', 123, 'entity_reference:entity_reference_entity_view', {view_mode: 'teaser'}) }}
Tips
- Configure separate embed buttons for different entity types (one for media, one for nodes) to keep the toolbar organized and limit selection scope for editors
- Use bundle restrictions on embed buttons to prevent editors from embedding inappropriate content types (e.g., restrict to 'Article' nodes only for a blog embed button)
- Enable the review step in Entity Browser settings to let editors verify their selection before configuring display options
- The rendered_entity_mode configuration in entity_embed.settings can simplify the display plugin dropdown by showing view modes at the top level
- Alt and title text overrides for media images use the special value '""' (two double quotes) to set explicitly empty alt text, distinguishing from inheriting the media's alt text
- Use hook_entity_embed_display_plugins_for_context_alter to dynamically filter available display options based on the specific entity being embedded
- Embedded entities are rendered with 'embedded-entity' CSS class for targeted styling
Technical Details
Admin Pages 3
/admin/config/content/embed
Lists all configured embed buttons including entity embed buttons. From here you can add, edit, or delete embed buttons that appear in the CKEditor toolbar.
/admin/config/content/embed/add
Create a new embed button for embedding entities in text content. This form allows you to configure the entity type, bundle restrictions, display plugins, and optional Entity Browser integration.
/admin/config/content/formats/manage/{format_id}
Configure text format settings including the Entity Embed filter and CKEditor button placement.
Hooks 7
hook_entity_embed_display_plugins_alter
Alter the Entity Embed Display plugin definitions globally. Use this to modify, add, or remove display plugin definitions.
hook_entity_embed_display_plugins_for_context_alter
Filter Entity Embed Display plugins based on context. Use this to remove plugins that shouldn't be available for specific entities or embed buttons.
hook_entity_embed_context_alter
Alter the context array before an embedded entity is rendered. Allows modification of context values that will be passed to the display plugin.
hook_ENTITY_TYPE_embed_context_alter
Entity type-specific variant of hook_entity_embed_context_alter. Replace ENTITY_TYPE with the entity type machine name (e.g., hook_node_embed_context_alter).
hook_entity_embed_alter
Alter the render array after an embedded entity has been built. This is called after the display plugin has generated the build array.
hook_ENTITY_TYPE_embed_alter
Entity type-specific variant of hook_entity_embed_alter. Replace ENTITY_TYPE with the entity type machine name.
hook_entity_embed_values_alter
Alter the values before they are submitted to the WYSIWYG editor. Called in the embed dialog form submission.
Troubleshooting 7
Ensure the 'Display embedded entities' filter is enabled for the text format and the embed button has been added to the CKEditor toolbar in the text format configuration.
The entity_embed filter is not enabled or not processing. Enable 'Display embedded entities' filter for the text format. Check filter processing order - entity_embed should run after filter_align, filter_caption, and filter_html_image_secure.
If using 'Limit allowed HTML tags' filter, ensure drupal-entity tag is whitelisted with all required attributes: data-entity-type, data-entity-uuid, data-entity-embed-display, data-entity-embed-display-settings, data-align, data-caption, data-embed-button, alt, title.
The entity type may not have compatible Entity Embed Display plugins, or the embed button configuration restricts available plugins. Check embed button settings and ensure the entity type has view modes or compatible field formatters.
Only Entity Browser instances with compatible display plugins are available. Browsers using 'modal' or 'standalone' displays are filtered out. Create or configure an entity browser with 'iframe' or other compatible display.
The current user may not have view permission for the embedded entity, or the entity has been deleted. Check entity permissions and verify the entity still exists.
An entity contains an embed of itself or creates a circular reference chain. The module has built-in protection (limit: 20 recursions) but you should review content to remove circular embeds.
Security Notes 5
- Entity embedding respects Drupal's entity access system - entities are only rendered if the current user has view permission
- The filter automatically handles missing or deleted entities gracefully, displaying a placeholder instead of errors
- HTML in captions is escaped before storage to prevent XSS attacks
- Entity UUIDs are preferred over entity IDs for embedding to prevent issues with content staging and migration
- The module validates that embedded entities exist and are accessible during both editor dialog and filter processing