Frequently Asked Questions

How is SDC different from Twig-based theming?

SDC can help with building a common design system with independent or combined UI elements following atomic design principles. These elements can then be used/reused in one or more themes. 

What is the advantage of using SDC for Drupal themes instead of the current approach?

The main advantage is that it allows  frontend developers to create components without requiring them to learn Drupal specific theming concepts; however, someone will still need to understand Drupal concepts in order to utilize these components within templates.

Is there a Drupal-9-compatible patch?

There is no specific Drupal 9 patch; however, there is a contrib module that supports utilizing SDC in Drupal 9. 

Can I start writing SDC style components now?

Yes! To get started check out the quickstart guide.

How can I declare dependencies for my component?

Adding a dependency for a component can be done within the *.component.yml file by including a libraryOverrides key.

Also, because Drupal automatically generates libraries for SDCs, you can include an SDC library just like any other dependency.

Below is an example for a component utilizing several Drupal core libraries and another auto-generated theme component library. 

libraryOverrides:
  dependencies:
    - core/drupal
    - core/once
    - core/components.my-theme--another-component

Can a module override components?

No, modules cannot override components. Only themes can.

How do I override a component?

Only themes can override components, and there are two important requirements to do so: 

1. Create a top level replaces key in the *.component.yml file of the component you want to override
   

   ​​​​​​​replaces: 'sdc_module_test:my-component'

2. The component needs to have a defined schema.

It is important to note that modules cannot override components, and only components that have a defined schema can replace and be replaced by others.

See Overriding components provided by other modules or themes.

Does SDC handle attributes, title_suffix, is_admin, etc?

By design, SDC renderables don't pass through the Theme Manager, so their templates don't receive the default attributes from ::getDefaultTemplateVariables() :

• attributes
• title_attributes
• content_attributes
• title_prefix
• title_suffix
• db_is_active
• is_admin
• logged_in
• directory

However, SDC itself is automatically adding those variables:

• attributes (if missing): an \Drupal\Core\Template\Attribute object, like the Theme Manager is doing for other templates.
• componentMetadata: with some information useful for debugging:
  • path - The path to the component relative to the web root.
  • machineName - Machine name of the component
  • status - Status of the component. Defaults to stable.
  • name - Name of the component.
  • group- Group of the component. Defaults to "All Components "
• (When Add component variants to SDC variant will be merged: variant)

Everything else is coming from slots & props data defined in the component definition.

Why some PHP namespaces are used in props schema?

You may find this in some SDC definitions:

name: 'My component'
props:
  type: object
  properties:
    body_attributes:
      type: 'Drupal\Core\Template\Attribute'

This is a trick to avoid triggering the JSON schema validator. In March 2025, it is still useful for \Drupal\Core\Template\Attribute objects sent as props but:

• it is not necessary to add this for the attributes prop itself because it is automatically added to the template anyway
• it must be used for other kind of props. Let's use standard JSON schema instead, in order to not skip the validation. In other words, except sometimes Attribute, never send a PHP object as a prop value.
• however, you can send PHP objects as slots values if they implement Stringable or RenderableInterface

How can I attach additional CSS/JS to my component?

Adding additional libraries for a component can be done within the *.component.yml file, by including a libraryOverrides key. Everything under the library overrides key follows standard Drupal structure. 

libraryOverrides:
  css:
    component:
      tabs.css: {}
      additional-styles.css: {}
  js:
    my-component.js: { attributes: { defer: true } }
    my-other-file.js: {}

How can I override an upstream component’s libraries?

When using a component from an upstream theme or module, you can override its styles, JavaScript, or both. via your `THEME.info.yml`’s `libraries-override`. To override or omit an entire library, you can do this:

# Override the entire library:
libraries-override:
  core/components.some-theme--some-component: my-theme/my-library

# Omit the entire library:
libraries-override:
  core/components.some-theme--some-component: false

If you want to override or omit a specific file, you’ll need to find the path to that file relative to the core/ directory. Then override it like any other library file:

# Override a specific file:
libraries-override:
  core/components.some-theme--some-component:
    css:
      component:
        ../themes/contrib/some-theme/components/some-component/some-component.css: my-overrides/some-component.css

# Omit a specific file:
libraries-override:
  core/components.some-theme--some-component:
    css:
      component:
        ../themes/contrib/some-theme/components/some-component/some-component.css: false

Are schema’s mandatory when defining components?

Schemas are not mandatory when defining components in themes; however components without schema can not be overridden. In order to enforce that all components within a theme contain schema, add enforce_prop_schemas: true to your theme.info.yml file.

What are the best practices?

We are currently in the process of determining that. All of the community testing and feedback help shape what best practices look like. These will continue to evolve over time as this module becomes more stable.

Some of them are currently being evaluated as a set of validation rules implemented in sdc_devel module.

Can SDC be used inside of a module?

Yes, see for example https://www.drupal.org/project/sdc_examples.

Can I use this approach with Atomic Design?

Yes. Components within the components directory can be nested under arbitrary directories. So it's perfectly acceptable to have a card directory within a molecules directory.

How can I pass arbitrary HTML into a component?

You should consider using a slot. Read the documentation to familiarize yourself with the differences between props and slots, which can be summarized as follows:

Definitions of the component’s inputs take the form of props (for data whose type and structure is well defined) and slots (for data with an unknown structure, like nested components). 

When using include() function, if you try to pass directly the markup, Twig will escape your string and the markup will be lost.

{% include 'mytheme:mycomponent' with {
  body: '<p><em>my</em> html</p>' <---- will get escaped, HTML will be lost.
}%}

So you need to do this instead:

{% set body %}
  <p><em>Any</em> html will be passed along!</p>
{% endset %}

{{ include('mytheme:mycomponent', {
  body: body
}, with_context = false) }}

When using the embed tag (because you are printing slots with Twig blocks in your component template), you need to put the markup inside a Twig block:

{% embed 'mytheme:mycomponent' %}
  {% block body %}
    <p><em>Any</em> html will be passed along!</p>
  {% endblock %}
{% endembed %}

Can I use composer packages in SDC?

No.

Will SDC support variants?

This is under consideration. See #3390712.

How do I use the render element?

An SDC-based component can be rendered with a special render element described in the documentation under "Using Your Component through a Render Array," where you will also find an example code snippet.

Can we preprocess variables with SDC?

No. SDC does not  support preprocessing variables by design. 

However, this is an on-going discussion. See #3321203.

How would I use components within my node/user/media/field/block... template?

Use SDC components in a Twig template file using Twig's built-in include function and/or embed tag. See Using your new single-directory component for more information.

How do I use components within other components?

You can combine and nest components within other components, similar to how you nest conventional Twig templates in Drupal using embed or include tags. See: "Using Your Component Through another Template."

However, instead of hardcoding components calls in component templates, instead of including like that:

<div class="card__actions">
 {{ include("my_theme:button", {...}, with_context_false) }}
 {{ include("my_theme:button", {...}, with_context_false) }}
</div>

Or like that if you use Twig blocks:

<div class="card__actions">
 {{ embed "my_theme:button" only %}... {% endembed %}
 {{ embed "my_theme:button" only %}... {% endembed %}
</div>

It is better to use slots and pass children component from the outside.

What are props and slots in Drupal SDC theming (with examples)? 

See this doc page.

Can I use (attach) only the assets library (CSS/JS) of a component inside a Twig template?

Yes. For each component Drupal adds a library with the name "core/components.[THEME_OR_MODULE_NAME]--[COMPONENT_NAME_WITH_DASHES]".

For example, for a component with the name "my-banner" on theme "my_theme" the default CSS/JS library name is "core/components.my_theme--my-banner" so in a Twig template you can attach the library like this.

{{ attach_library('core/components.my_theme--my-banner') }}

Before SDC became stable, it used to be sdc/my_theme--my-banner.

You can do the same thing with any additional libraries defined on the sdc component.

If a component is defined in a module, can I attach additional assets to that component in my theme?

Yes. As mentioned above, each component creates a library. So, you can use libraries-extend.

Should I attach the CSS and JS for all components on all requests?

It may be a good idea to attach all the assets for your components on all requests. This will likely increase the cache hit ratio for the visitor's browser's cache. Depending of the setup, this can have a dramatic effect on your website's front-end performance.

To do so, add the library core/components.all as a dependency in your theme. If you are using the experimental version of SDC, you need to use sdc/all instead.

My component doesn't have props, how do I write its schema? 

Component schema is mandatory for validation, and for integration with display building modules like SDC Display or UI Patterns. The way to declare empty props is not by leaving them out but by actually saying they are empty. Perhaps a schema like this would work:

$schema: https://git.drupalcode.org/project/drupal/-/raw/HEAD/core/assets/v1/metadata.schema.json
name: Info Card

# Declare empty props.
props:
  type: object
  properties: {}

slots:
  card_content:
    title: Content
    required: true

How does cl_components module fit in?

cl_components module (Component Libraries: Components) is obsolete. The functionality it provided is now in Drupal core.