Template suggestions in Drupal 8 & Drupal 9

This is nothing new in Drupal 8: every part of a page is rendered with a template.

There is a whole bunch of base templates:

• html.html.twig, which renders the doctype and the content of the <head> tag, and opens and closes the <body> tag
• page.html.twig, which starts where html.html.twig stops, that is to say inside the body tag
• region.html.twig for the content of a region (header, footer, content... in short, the regions defined in our theme)
• node.html.twig for the content of a node
• field.html.twig for a field defined on a content type or an entity
• block.html.twig for blocks...

Let's take as an example the node.html.twig template, which is used to display all nodes (page, article...).

These templates can be made more specific: if, for example, we want a special template for nodes of type "article", we can copy the node.html.twig file to node--article.html.twig.

There are other suggestions too:

• node--NID.html.twig, replacing NID with the id of the node in question
• node--VIEW_MODE.html.twig to use a different template when the node is displayed in "teaser" or "full" mode
• ...

You can easily find out the possible template names for an element by enabling Twig debug and looking at the HTML code of the page:

The items prefixed with * are the possible template names, and the one prefixed with x is the one actually used: these are the template suggestions. There is a set of base suggestions that is enough in most cases, but you may also want to define a more specific template.

Defining your own template suggestion

In Drupal 7 we used HOOK_preprocess_HOOK for this; in Drupal 8 a dedicated hook is available: HOOK_theme_suggestions_HOOK.

The first "HOOK" must be replaced with the name of the module implementing the hook, the second with the name of the element we want to add a suggestion for.

If we have a module called "mon_module" and we want to add a template suggestion for nodes (node), we define the following function:

function monmodule_theme_suggestions_node(array $variables) {
  //...
}

This function must return an array of suggestions containing the new options, for example:

function monmodule_theme_suggestions_node(array $variables) {
  $suggestions = [];
  $suggestions[] = 'node__montemplate';
  return $suggestions;
}

Note: when defining a template suggestion in code, you must replace the "--" with "__".

So:

If we want a specific html template per content type:

function monmodule_theme_suggestions_html(array $variables) {
  $suggestions = [];
  if (\Drupal::routeMatch()->getRouteName() == 'entity.node.canonical') {
    $bundle = \Drupal::routeMatch()->getParameter('node')->bundle();
    $suggestions[] = 'html__' . bundle;
  }
  return $suggestions;
}

The same thing for "page":

function monmodule_theme_suggestions_page(array $variables) {
  $suggestions = [];
  if (\Drupal::routeMatch()->getRouteName() == 'entity.node.canonical') {
    $bundle = \Drupal::routeMatch()->getParameter('node')->bundle();
    $suggestions[] = 'page__'  .  $bundle;
  }
  return $suggestions;
}

And for "region":

function monmodule_theme_suggestions_region(array $variables) {
  $suggestions = [];
  if (\Drupal::routeMatch()->getRouteName() == 'entity.node.canonical') {
    $bundle = \Drupal::routeMatch()->getParameter('node')->bundle();
    $suggestions[] = $variables['theme_hook_original'] . '__' . $variables['elements']['#region' ] . '__' . $bundle;
  }
  return $suggestions;
}

Note: here I used the $variables['theme_hook_original'] variable, which contains the prefix to use for each template (here "region"), while the $variables['elements']['#region'] variable contains the name of the region.

Here are the templates available this way for the "header" region when viewing content of type "article":

Of course, you can add several suggestions for the same element.