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.

The name of the component should be used for naming the library. so that it's name is predictable to include from another component. This means that if the status-messages component only has 1 library, it should be defined with the name status-messages. 

As a suggestion, we also recommend to name your .scss or .js files the same way: status-messages.scss and status-messages.js. This helps on a developer's experience: When someone has the status-messages.js file open in their IDE or a browser is reporting an error in status-messages.js, it's immediately clear to which component that file belongs.

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:

YAML Created with Sketch.
Twig Created with Sketch.
Twig Created with Sketch.
sass Created with Sketch.

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.