Component Libraries

Registers “component libraries” defined by your theme or module as Twig namespaces.

What are Twig namespaces?

Twig natively offers a feature called “namespaced paths”. Drupal core registers many Twig namespaces so that you can reference the Twig templates from specific modules or themes. For example, you may have seen this:

{% extends "@classy/block/block--system-menu-block.html.twig" %}

The text, @classy, indicates the Twig namespace we wish to use when getting the twig template.

Why use a custom Twig namespace?

Modern front-end development techniques means a website needs a component library where each component is concerned about a specific design element.

But Drupal core does not yet provide a component library for its design. Instead, Drupal core registers a Twig namespace for every module and theme in your installation (@bartik, @system, etc.) And all of those Twig templates are designed for specific Drupal theme hooks and data (nodes, comments, views, etc.) and must be placed in a /templates directory inside a module or theme.

Ideally, we would put our component library's Twig templates in a separate directory from the D8-style Twig templates. But Drupal core makes it very difficult to use Twig templates not placed in a /templates directory.

The Component Libraries module allows you to specify a different directory for you component library's Twig files and allows you to register a unique Twig namespace for those files.

Here's how you would register a "myLib" component library; in your theme's or module's .info.yml file, add these lines:

component-libraries:
  myLib:
    paths:
      - myLibFiles

If you have a [my theme directory]/myLibfiles/box/box.twig Twig template, you can extend, include or embed it using a reference to @myLib/box/box.twig. For example, in your [my theme directory]/templates/page.html.twig you could add:

{% include "@myLib/box/box.twig" %}

This allows you to specify the exact component in your component library no matter what Drupal decides it should use for the D8-style Twig template.