Custom Elements

Provides a framework for rendering Drupal entities as custom HTML elements (Web Components) for decoupled frontend architectures.

custom_elements

123 sites

drupal.org

decoupled headless web-components vue react API json frontend custom-elements progressive-decoupling

Drupal 10 Drupal 11

Install

Drupal 11, 10 v3.3.1

composer require 'drupal/custom_elements:^3.3'

Overview

The Custom Elements module provides a comprehensive framework for rendering Drupal data (entities, fields) into custom elements markup. Custom elements can be easily rendered by frontend components using Web Components or various JavaScript frontend frameworks like Vue.js or React.

This enables Drupal to render high-level theme components while the actual rendering is handled by a frontend application. The module supports both progressive decoupling (mixing custom elements with traditional Drupal output) and full decoupling (API responses with custom element markup or JSON).

Key capabilities include: UI configuration for custom element output per entity view mode, API for building nested custom element trees with cache metadata, serialization to HTML markup or JSON representation, and extensible processor system for customizing how data is rendered into custom elements.

Features

Render Drupal entities as custom HTML elements (Web Components) for frontend framework consumption
UI-based configuration of custom element output per entity type, bundle, and view mode via Custom Elements Display entities
Two serialization formats: HTML markup (Web Component style or Vue 3 style) and JSON (explicit or legacy format)
Layout Builder integration for building custom elements from layout sections and regions
Automatic processing mode that intelligently maps fields to attributes or slots based on field complexity
Pluggable Custom Element Field Formatters for fine-grained control over individual field output
Extensible processor system for customizing how entities and fields are rendered into custom elements
Preview providers for JSON structure preview, markup code preview, and Nuxt.js frontend preview
Support for nested custom elements with proper cache metadata bubbling
Dynamic permissions per entity type for administering custom element displays

Use Cases

Progressive Decoupling with Web Components

Use custom elements as part of a regular Drupal-rendered response where Web Components or JavaScript takes over rendering in the browser. Enable 'Force custom elements rendering' on specific entity view modes, and add your Web Component JavaScript to the custom_elements/main library in your theme.

Full Decoupling with Vue.js/Nuxt

Build a completely decoupled frontend using Vue.js/Nuxt while Drupal serves as a headless CMS. Use Lupus Custom Elements Renderer to serve JSON API responses. Configure Vue 3 markup style for slot syntax compatibility. The Nuxt preview provider allows editing content with live previews.

Layout Builder Integration

Build complex page layouts using Drupal's Layout Builder while outputting them as custom elements. Each layout section becomes a <drupal-layout> element with regions as slots. Blocks within regions render as nested custom elements.

Entity Reference Field Rendering

Render referenced entities (like media, paragraphs, or other content) as nested custom elements. Use the 'Custom element: Rendered entity' formatter with configurable view mode and optional flattening to merge properties into the parent element.

Image Field with Style Processing

Output image fields with image style processing. The Image formatter generates URLs for styled images along with alt text, width, and height attributes. Enable flatten option to output image properties as separate attributes on the parent element.

API Development and Debugging

Use the JSON preview provider in the Custom Elements Display edit form to see exactly what JSON structure will be sent to your frontend. The explicit JSON format clearly separates props from slots for easier frontend consumption.

Tips

View modes with names starting with 'custom_elements' automatically have custom elements rendering enabled
Use the 'Flatten' option on entity reference and file formatters to merge referenced entity properties directly into the parent element
The processor priority system allows custom modules to override default field handling by registering higher-priority processor services
Cache metadata properly bubbles through nested custom elements, ensuring correct cache invalidation
The CustomElement::$removeFieldPrefix static property can be set in settings.php to globally remove 'field_' prefixes from output keys

Dependencies

Field UI (for custom_elements_ui)

Related Projects

Lupus Custom Elements Renderer

Switches Drupal's main content renderer to provide API responses using custom elements markup or JSON serialization for complete pages. Essential for full decoupling scenarios.

Lupus Decoupled Drupal

Complete decoupled setup package building on Lupus CE Renderer. Provides ready-to-use decoupled Drupal architecture at lupus-decoupled.org.

Layout Builder

Custom elements can be built from Layout Builder sections, rendering layout sections as <drupal-layout> elements with region slots containing block custom elements.

Paragraphs

The ParagraphFieldItemProcessor handles paragraph entity references, rendering them as nested custom elements. Thunder integration provides pre-built configurations.

Canvas (experimental)

Optional integration with Drupal's Canvas module for development and testing. Requires Drupal 11.2+, PHP 8.3+, and Canvas 1.x.

Field UI

Required for the custom_elements_ui submodule to add Custom Element display tabs to entity type configuration.

Technical Details

Custom Elements settings /admin/config/system/custom-elements

Configure global settings for custom elements rendering including markup style, JSON format, and default rendering mode.

Administer site configuration

Required to access the Custom Elements settings page

{Entity type}: Administer custom element

Dynamic permission generated per entity type with field UI. Allows administering custom element displays for that entity type.

hook_custom_element_entity_defaults_alter

Allows preparing custom element defaults before it is processed. Called when generating custom elements from entities to allow modules to set default tag names, prefixes, or attributes.

hook_custom_element_entity_alter

Allows altering custom elements after generation, before they are rendered. Called after all field processing is complete to allow final modifications.

Custom elements not rendering for a view mode

Ensure 'Force custom elements rendering' is enabled in the entity's Manage Display tab for that view mode, or that the view mode name starts with 'custom_elements' which auto-enables rendering.

Layout Builder integration not working

Both the entity view display AND the Custom Elements Display must have 'Use Layout Builder' enabled. Check both settings and ensure Layout Builder module is installed.

JSON format differs from expected

Check the JSON serialization format setting at /admin/config/system/custom-elements. 'Explicit' format separates props/slots, 'Legacy' format mixes them. Existing sites may be on legacy format after upgrade.

Upgrading from 2.x breaks existing setup

Version 3.x uses configuration-based rendering. Create Custom Elements Displays for your entity view modes and enable 'Automatic Processing' option to replicate 2.x behavior. See change records at drupal.org/list-changes/custom_elements.

Custom Elements displays respect Drupal's field access system - fields users cannot access are not included in output
JSON output uses proper escaping to prevent XSS when rendering markup
The module does not expose any data that wouldn't be accessible through normal entity view rendering