Component naming convention

Basics #

In practice you could choose the name of the folders of each component yourself. You could name something: messages-thingy and that could work.

But to avoid complexity and a high randomness-factor, we will follow the BEM-naming. This naming convention is used by Drupal and can be best seen in the names of the .html.twig files.

If you are theming messages for example, then have a look at the name of the .html.twig file. You can find this by enabling template suggestions.

In this example the HTML comes from status-messages.html.twig, so this means that the name of this component is status-messages.

BEM-variations #

If you are theming a teaser of a article-node, then the template will likely be node--article--teaser.html.twig. Therefor the naming of the folder will be node--article--teaser.

In the BEM-naming convention, a double hyphen -- means that the part on the right is a variation of the part on the left. So in the above example it means that

  • node is the base for the article-variation of a node.
  • node--article is the base for the teaser-variation of article nodes
  • node--article--teaser is the teaser-variation of article nodes

For nodes, Drupal dynamically adds names of components based upon content-type and view-mode.

This naming gives each component a good predictability of what it does. It also illustrates in what context a component will be used. The name is understandable for both backend and frontend.

Multiple .html.twig files #

In the previous chapter we covered that naming a component is often straight forward. Name it according to the template file that Drupal is using.

But what if we have multiple templates in the same component? Some templates just belong together. An example of this could be the theming of the menu, where we are relying on multiple template files:

main-menu
dist
YAML Created with Sketch.
libraries.yml
Twig Created with Sketch.
main-menu.html.twig
Twig Created with Sketch.
menu-item.html.twig
sass Created with Sketch.
main-menu.scss

If you decide to have multiple templates in to a single component, then you might wonder of what to name the folder. The rule is to name the component in this case the same as the template that is the most high up in the DOM.

So in the above example, the template that is the most high up in the dom will be main-menu.html.twig. menu-item.html.twig will be used as children of the menu itself. Therefor the component should be named main-menu.

No .html.twig files #

It is possible to create components that have no .html.twig files defined in them. If this is the case, you can choose the name of your component, as it is now an abstraction that has nothing to do with Drupal.

Nesting #

Some components will be the base for other components, we should nest components too. We nest them based on their BEM-name.

This nesting-standard helps us find our components more easily, and allows us to have an overview of what variations exist.

components
_global
node
node
node--article
node--article--full
node--article--teaser
node--blog
node--blog--full
node--blog--teaser