Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท Themes and Twig

Template Suggestions and Overrides

Override Drupal templates safely: how Drupal picks a template, naming with double hyphens, custom suggestions in PHP, Twig debug and a template-resolver stand-in.

Drupal core and modules ship with hundreds of Twig templates: one for a page, one for a node, one for a block, one for a field, one for a form element. To change the markup you do not edit those files. You copy a template into your theme, adjust it, and clear the cache. Drupal then prefers your copy. The system that decides which file wins is called template suggestions, and understanding it saves hours.

This lesson is read-only for the Drupal parts. A JavaScript stand-in reproduces the lookup rule so you can experiment with file names.

The lookup rule

Every theme hook (for example node, block, field) has a base template such as node.html.twig. For a specific render, Drupal builds a list of more specific names called suggestions, from most specific to least, and uses the first file that exists in the active theme chain. Words in a name are separated by a double hyphen --, and underscores in suggestion names become single hyphens in file names.

For an Article node shown in teaser mode, the list is:

TEXT
node--article--teaser.html.twig
node--123--teaser.html.twig   (123 is the node ID; this is checked before the type)
node--article.html.twig
node--123.html.twig
node--teaser.html.twig
node.html.twig

The exact order depends on core, but the principle is stable: the more specific file wins, and a single node.html.twig handles everything that has no better match.

Node.js Stand-in: pick the most specific template

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that article + teaser found node--article.html.twig first, because the more specific node--article--teaser does not exist, and that the page in full mode fell back to core.

Finding the right template

Turn on Twig debug (see Twig syntax basics) and inspect the page source. You will see comments like:

HTML
<!-- THEME DEBUG -->
<!-- THEME HOOK: 'node' -->
<!-- FILE NAME SUGGESTIONS:
   * node--article--teaser.html.twig
   * node--article.html.twig
   x node.html.twig
-->
<!-- BEGIN OUTPUT from 'core/themes/olivero/templates/content/node.html.twig' -->

The x marks the file used; the others are the names you may create. Copy the BEGIN OUTPUT file into your theme's templates/ folder (any subfolder works, Drupal scans recursively), rename it to a more specific suggestion if you want, edit, then drush cr.

Common template families

  • html.html.twig: the outer document (<html>, <head>, <body>).
  • page.html.twig: the page layout with regions; page--front.html.twig, page--node--123.html.twig suggestions.
  • region.html.twig, block.html.twig, block--system-branding-block.html.twig.
  • node.html.twig, field.html.twig, field--field-image.html.twig, field--node--title--article.html.twig.
  • views-view.html.twig, views-view-unformatted.html.twig, views-view-fields.html.twig, views-view-field.html.twig.
  • form-element.html.twig, input.html.twig, menu.html.twig, comment.html.twig, user.html.twig, taxonomy-term.html.twig.

Views have suggestions by view ID and display ID, such as views-view--blog--page-1.html.twig.

Adding your own suggestions

When core's list is not enough, add a suggestion in PHP with hook_theme_suggestions_HOOK_alter in sunrise.theme:

PHP
<?php

use Drupal\node\NodeInterface;

function sunrise_theme_suggestions_node_alter(array &$suggestions, array $variables) {
  /** @var \Drupal\node\NodeInterface $node */
  $node = $variables['elements']['#node'];
  if ($node->hasField('field_layout') && !$node->get('field_layout')->isEmpty()) {
    $layout = $node->get('field_layout')->value;
    $suggestions[] = 'node__' . $node->bundle() . '__layout_' . $layout;
  }
}

This makes node--article--layout-wide.html.twig a valid file. Use underscores in PHP, hyphens in file names. Later suggestions in the array win. You can also alter suggestions based on the route, the logged-in role or a view mode:

PHP
function sunrise_theme_suggestions_page_alter(array &$suggestions, array $variables) {
  if (\Drupal::currentUser()->isAnonymous()) {
    $suggestions[] = 'page__anonymous';
  }
}

Be careful: suggestions that depend on the user or request affect caching. Anything you read there must be declared as a cache context (see caching), otherwise one user's markup may be reused for another.

Node.js Stand-in: adding a custom suggestion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Overriding other things

Besides templates, a theme can override a library (libraries-override), extend one (libraries-extend), remove core CSS, or replace a theme function through preprocess. Examples in the info file:

YAML
libraries-override:
  system/base: false
  core/drupal.dialog:
    css:
      component:
        misc/dialog/dialog.css: css/my-dialog.css
libraries-extend:
  core/drupal.dialog:
    - sunrise/dialog

Common mistakes

  • Naming a file node_article.html.twig instead of node--article.html.twig.
  • Not clearing the cache after adding a template; new files are only found after a rebuild.
  • Copying a whole template when a small change in a preprocess function would do, which makes upgrades harder.
  • Relying on node IDs in file names: IDs differ between environments. Prefer type, view mode or a field.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file name targets Article nodes in teaser mode?

    Double hyphens separate the hook name from its suggestion parts.
  2. 2. How do you see which template Drupal used?

    Debug mode prints suggestions and marks the file used with an x.
  3. 3. In a PHP suggestion alter hook, you write the suggestion as

    PHP uses underscores; the file name turns double underscores into double hyphens.
  4. 4. Why can a user-based suggestion be risky?

    Rendered output is cached; suggestions that vary by user need the right cache contexts.

Summary

  • Drupal picks the most specific existing template from a list of suggestions.
  • Use -- in file names, __ in PHP suggestion names.
  • Turn on Twig debug to find the right file to copy.
  • Add suggestions with hook_theme_suggestions_HOOK_alter, and mind caching.
  • Prefer small overrides over copying large templates.

Next: Preprocess Functions and Libraries