Single Directory Components: Display

Integrates Drupal fields and view modes with Single Directory Components (SDC), allowing entity displays to be rendered through component templates.

sdc_display
1,244 sites
47
drupal.org
gui api field theme
SDC components single-directory-components theming field-display view-modes field-formatters component-based frontend display-modes field-group

Overview

SDC Display bridges Drupal's content display system with Single Directory Components (SDC), the modern component-based theming system introduced in Drupal 10.1. This module enables site builders to map entity fields directly to component props and slots, eliminating the need for custom preprocess hooks or theme overrides.

The module operates at three distinct levels: individual field formatters can wrap their output in a component, entire view modes can render through a component template with fields mapped to specific inputs, and field groups can be rendered using SDC components. This provides unprecedented flexibility in how content is displayed while maintaining a clean separation between data and presentation.

By leveraging component-based architecture, SDC Display promotes reusable, maintainable frontend code. Components define their own schemas (props and slots), and this module automatically generates configuration forms based on those schemas, allowing content editors and site builders to configure mappings through Drupal's familiar admin interface.

Features

  • Render individual field formatters through SDC components with configurable prop/slot mappings
  • Wrap entire view modes in components, mapping multiple entity fields to component inputs
  • Field Group integration allowing groups of fields to render as unified components
  • Static and dynamic mapping support - static values as fallbacks when field values are empty
  • Component selector with tag-based filtering to show only relevant components
  • Auto-generated forms based on component JSON schemas for prop/slot configuration
  • AJAX-powered component selection that updates available mappings dynamically
  • Entity metadata automatically passed to components (id, entity_type, bundle)
  • Seamless integration with Drupal's existing field formatter and view mode systems
  • Support for complex nested prop structures through schema-forms library

Use Cases

Card Component for Content Teasers

Create a reusable card component with props for image, title, summary, and link. Configure the Article teaser view mode to use this card component, mapping the image field to the image prop, title to the title prop, body summary to the summary slot, and node URL to the link prop. All article teasers now render consistently through your card component.

Hero Banner for Landing Pages

Design a hero banner component with slots for headline, body content, and CTA buttons. On landing page view modes, enable SDC Display and map the page title to headline, a WYSIWYG body field to the content slot, and link fields to the CTA slot. Static values provide fallback CTAs when none are configured.

Product Grid Items

Build a product display component with props for price, availability, image URL, and a slot for description. Map commerce product fields to these inputs, using static values for 'Add to Cart' button text. Components maintain visual consistency across all product displays.

Grouped Contact Information

Use Field Group to group address, phone, and email fields. Apply the SDC Display field group formatter with a contact-card component. Map address to address slot, phone to phone prop, email to email prop. The grouped fields render as a cohesive contact card component.

Author Bylines

Create an author byline component for articles. At the field level, configure the Author reference field formatter to render through the byline component, mapping the rendered author display to the author slot. Each author field instance renders through the component.

Tips

  • Tag components specifically for their intended use - field formatters typically need single-input components while view mode components should accept multiple inputs
  • Use the static mappings as required value fallbacks - if a prop is required in the component schema, always provide a static value
  • For complex data transformations, consider using the NoMarkup module to pass raw field data instead of rendered output to component props
  • Components receive entity metadata (id, entity_type, bundle) automatically as props, useful for dynamic behavior
  • Multiple fields can be mapped to a single slot - they render in the display table's weight order
  • Test with empty field values to ensure static fallbacks work correctly
  • Use Field Group integration for partial component rendering when you don't want to wrap the entire entity

Technical Details

Admin Pages 2
Manage Display (Content Type) /admin/structure/types/manage/{bundle}/display

Configure how entity fields are displayed in different view modes. SDC Display adds options to each field formatter and to the view mode as a whole.

Field Formatter SDC Settings /admin/structure/types/manage/{bundle}/display (Field Formatter Settings)

Each individual field formatter gains SDC Display options in its settings form, allowing single fields to render through components.

Hooks 5
hook_field_formatter_third_party_settings_form

Adds SDC Display options to every field formatter's settings form, enabling component-based rendering at the field level.

hook_field_formatter_settings_summary_alter

Modifies the field formatter settings summary to show SDC Display configuration status.

hook_preprocess_field

Preprocesses field output to wrap it in the configured SDC component when enabled.

hook_form_entity_view_display_edit_form_alter

Adds view mode-level SDC Display configuration to the entity display edit form.

hook_entity_view_alter

Alters the entity render array to wrap the entire view mode output in the configured SDC component.

Troubleshooting 5
Component not appearing in selector

Ensure your component is tagged with 'sdc_display:field_formatter' or 'sdc_display:view_mode' in its component.yml file. Clear caches after adding tags.

Mappings not saving

This can occur when formatter settings forms interfere with view mode settings. The module uses raw user input as a workaround. Ensure JavaScript is enabled and no JS errors occur.

Component renders but fields are empty

Verify that the fields you want to map are enabled (not in the Disabled section) in the manage display form. Only enabled fields appear in mapping options.

Static values not displaying

Static values only display when mapped fields are empty. Check that the field doesn't have data, or remove the dynamic mapping to always show static values.

SDC options not showing on view mode form

SDC Display is disabled when Layout Builder is enabled for that view mode. Disable Layout Builder to use SDC Display, or use components within Layout Builder instead.