Template naming conventions

Overview

For each component (page, node, block, field, ...) Drupal looks for template names according to a certain pattern, and in a given order.
We will list a few of those here for illustration. See Twig Template Naming Conventions for the full list.

Example 1

page.html.twig is a generic template that will be used for all pages except for those pages for which more specific template files exist.

page--front.html.twig is an example of a more specific template file: if you add it to your theme, it will be used for the front page, while all other pages will use your generic page.html.twig.

Example 2

When Drupal needs to decide which template file to use to render a node on its own page (e.g. /node/42), it will first try to find the most specific template file.

Drupal will use the first template file it finds (simplified):

• try page--node--42.html.twig in your theme directory
• try page--node--42.html.twig in your base theme's directory (and its base theme directory, etc)
• try page--node.html twig in your theme directory
• try page--node.html.twig in your base theme directory
• try page.html.twig in your theme directory
• try page.html.twig in your base directory
• fall back to the default template (core/modules/system/templates/page.html.twig)

Pages

1. page--node--1.html.twig
2. page--node.html.twig
3. page.html.twig

→ note that the list goes from very specific to very generic.

Regions

1. region--[region_name].html.twig
2. region.html.twig

Nodes

1. node--[nodeid]--[viewmode].html.twig
2. node--[nodeid].html.twig
3. node--[content-type]--[viewmode].html.twig
4. node--[content-type].html.twig
5. node--[viewmode].html.twig
6. node.html.twig

Blocks

1. block--[module_name]--[block_id].html.twig
2. block--[block_id].html.twig
3. block--[module_name].html.twig
4. block.html.twig

→ note: in official documentation you might see references to a block's delta. This is the same thing as a block's machine_name or block_id.

The process is the same for every type of template file: Drupal will try to find the most specific template file according to its predefined patterns, and work its way down, gradually trying to find more generic template files, until it falls back on the default template file for that component.

You can compare this with the order of specificity used in Cascading Style Sheets: very specific CSS selectors will always have precedence over more generic selectors:

<style>
 p {font-size: 16px}
 p.extra-large { font-size: 32px}
</style>

In the above CSS example, all paragraphs will have a font size of 16px, except for the paragraphs with class 'extra-large', which will have a font size of 32px.

When the browser encounters these two conflicting rules for styling paragraphs, it will choose to apply the rules for the most specific selector.