Custom Elements
Provides a framework for rendering Drupal entities as custom HTML elements (Web Components) for decoupled frontend architectures.
custom_elements
インストール
composer require 'drupal/custom_elements:^3.3'
概要
Custom Elementsモジュールは、Drupalデータ（エンティティ、フィールド）をカスタムエレメントマークアップにレンダリングするための包括的なフレームワークを提供します。カスタムエレメントは、Web Componentsや、Vue.js、Reactなどの各種JavaScriptフロントエンドフレームワークを使用するフロントエンドコンポーネントで簡単にレンダリングできます。
これにより、Drupalは高レベルのテーマコンポーネントをレンダリングし、実際のレンダリングはフロントエンドアプリケーションが処理できるようになります。このモジュールは、プログレッシブデカップリング（カスタムエレメントと従来のDrupal出力の混在）と完全なデカップリング（カスタムエレメントマークアップまたはJSONによるAPIレスポンス）の両方をサポートします。
主な機能には、エンティティビューモードごとのカスタムエレメント出力のUI設定、キャッシュメタデータを持つネストされたカスタムエレメントツリーを構築するためのAPI、HTMLマークアップまたはJSON表現へのシリアライズ、データをカスタムエレメントにレンダリングする方法をカスタマイズするための拡張可能なプロセッサシステムが含まれます。
Features
- フロントエンドフレームワークで使用するために、DrupalエンティティをカスタムHTML要素（Web Components）としてレンダリング
- Custom Elements Displayエンティティを介した、エンティティタイプ、バンドル、ビューモードごとのカスタムエレメント出力のUIベース設定
- 2つのシリアライズ形式：HTMLマークアップ（Web Componentスタイルまたは Vue 3スタイル）とJSON（明示的形式またはレガシー形式）
- レイアウトセクションとリージョンからカスタムエレメントを構築するためのLayout Builder統合
- フィールドの複雑さに基づいてフィールドを属性またはスロットにインテリジェントにマッピングする自動処理モード
- 個々のフィールド出力をきめ細かく制御するためのプラガブルなCustom Element Field Formatter
- エンティティとフィールドをカスタムエレメントにレンダリングする方法をカスタマイズするための拡張可能なプロセッサシステム
- JSON構造プレビュー、マークアップコードプレビュー、Nuxt.jsフロントエンドプレビュー用のプレビュープロバイダー
- 適切なキャッシュメタデータバブリングを伴うネストされたカスタムエレメントのサポート
- カスタムエレメントディスプレイを管理するためのエンティティタイプごとの動的パーミッション
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
Technical Details
Admin Pages 1
/admin/config/system/custom-elements
Configure global settings for custom elements rendering including markup style, JSON format, and default rendering mode.
権限 2
Hooks 2
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.
Troubleshooting 4
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.
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.
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.
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.
Security Notes 3
- 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