Drupal Core Single Directory Components Introduce Component Variants

Drupal core’s Single Directory Components (SDC) now supports first-class component variants through a new root-level declaration, closing a major contributed-project blocker and laying groundwork for the upcoming 11.2.0 release. Merged on June 24, 2025, the update introduces a non-breaking API change that lets component authors define named variants with titles and descriptions, and lets render arrays specify the desired variant via a `#variant` key.

Component variants have long been a staple of UI frameworks, including Bootstrap cards offering vertical and horizontal layouts, and Material Design buttons providing text, outlined, raised, and unelevated styles, yet SDC previously required workaround patterns. Defining a `variant` prop as a simple string enum obscured documentation metadata, using verbose `anyOf` schemas became cumbersome, and inconsistent prop names made it impossible for external modules to detect variant support reliably.

The new solution mirrors SDC’s existing `slots` property. Component YAML declarations can now include a `variants` section alongside `props` and `slots`, for example:

```yaml
name: Card
variants:
 primary:
   title: Primary
   description: Standard card style
 inverted:
   title: Inverted
   description: Light-on-dark style
props: {}
slots: {}
```

When rendering a component, authors specify:

```php
[
 '#type' => 'component',
 '#component' => 'card',
 '#variant' => 'primary',
 '#props' => [],
]
```

This approach keeps the API backward-compatible while providing clear, structured metadata for each variant.

With the variants feature in place, contributed projects can be ported to Drupal 11 without resorting to custom hacks. The SDC FAQ documentation will be updated to reflect these changes, and future SDC enhancements, such as template-path declarations and schema references, stand ready for implementation.

For full details, see the issue page on Drupal.org: https://www.drupal.org/project/drupal/issues/3390712