Single Directory Components

Single Directory Components (SDC) are Drupal core's way of packaging one piece of user interface, such as a card or a button, in a single folder. The folder holds a YAML file that describes the component and its inputs, a Twig template for the markup, and optional CSS and JavaScript files. Templates can then reuse the component by name.

How it works in Drupal 11

SDC became part of core's render system in Drupal 10.3. The module and theme folders are scanned for a components directory (I read this in the ComponentPluginManager class of Drupal core 11.4.10). Each component sits in its own subfolder and its files share one name, for example components/notice/notice.component.yml and notice.twig.

The YAML file holds the component metadata. The keys name, status, props, slots, variants, tags and libraryOverrides are all in core's metadata schema. The status value must be one of experimental, stable, deprecated or obsolete. Props use JSON Schema. Core checks the values passed in against it, but it does so inside a PHP assert() call, so the check runs only where PHP assertions are enabled. If a notice.css or notice.js file exists next to the template, Drupal turns it into a library and attaches it when the component is used.

You call a component by its id, which is the extension name, a colon and the base name of its YAML file, such as olivero:teaser. In Twig you use include or embed. In PHP you use a render array with '#type' => 'component' and '#component'. Core 11.4.10 ships real examples: Olivero's teaser component and several components in the Umami demo theme.

Example

A notice component in a custom theme needs two files. First, my_theme/components/notice/notice.component.yml:

name: Notice
        status: stable
        props:
          type: object
          required:
            - tone
          properties:
            tone:
              type: string
              title: Tone
              enum: [info, warning]
        slots:
          body:
            title: Body

Second, notice.twig, where the slot is a Twig block:

<div class="notice notice--{{ tone }}">
          {% block body %}{% endblock %}
        </div>

Any template can then fill it in with {% embed 'my_theme:notice' with { tone: 'warning' } only %}{% block body %}Back up first.{% endblock %}{% endembed %}.

Common mistakes

• Forgetting the cache. The quickstart tells you to clear the cache after you create a component; until then Drupal does not find it.
• Relying on prop validation in production. Because the check sits inside assert(), a wrong value may pass unnoticed on a server where assertions are off. Test with assertions on.
• Passing markup as a prop. Props describe data. Put markup in a slot.
• Mismatched file names. Core takes the component name from the YAML file and looks for the Twig, CSS and JavaScript files under that same name, so a notice.component.yml next to a card.twig has no template.
• Leaving status: experimental on a finished component. The metadata schema describes that field as telling people whether the component can be safely used in production.

For marketing and content teams

Editors never touch the YAML or Twig. You feel SDC when a developer builds each design element once and every page that uses it stays consistent. It also matters for page builders: Drupal Canvas offers SDCs from a theme or module as pieces an editor can place visually. If your team plans a component library, ask developers to give every prop a clear title, because that is the text people will see.

Sources

• Drupal.org: Using Single-Directory Components
• Drupal.org: Single-Directory Components quickstart
• Drupal.org: Single Directory Components project page
• Drupal.org: Change record for obsolete modules (SDC section)
• Drupal core 11.4.10: ComponentPluginManager and component metadata schema
• Drupal Canvas 1.12.0: components documentation