Component naming convention
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
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
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.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.
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
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
nodeis the base for the
article-variation of a
node--articleis the base for the
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:
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
menu-item.html.twig will be used as children of the menu itself. Therefor the component should be named
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.
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.