Twig Template Suggestions

Drupal Twig Template Suggestions — How They Work

Drupal's theming system uses a template suggestion hierarchy to determine which Twig file to render for any given piece of content. When Drupal renders a node, block, field, or form, it looks for template files in order from most specific to least specific. The first file it finds in your active theme wins.

For example, when rendering an article node with ID 42 in full view mode, Drupal will look for templates in this order: node--42--full.html.twig, node--42.html.twig, node--article--full.html.twig, node--article.html.twig, node--full.html.twig, then finally node.html.twig. Place your custom template in your theme's templates/ directory with the correct name and clear the cache.

Where to Place Template Files

• Custom theme: themes/custom/mytheme/templates/
• Subdirectories are supported and recommended for organisation (e.g., templates/node/, templates/field/)
• After adding or renaming a template file, always run drush cr or clear the cache via Drupal admin.

Enabling Twig Debug Mode

To see exactly which template files Drupal is looking for and which one it selected, enable Twig debug in services.yml:

parameters:
  twig.config:
    debug: true

With debug on, Drupal outputs HTML comments showing the template suggestions hierarchy and the selected template for every rendered element.

Naming Conventions

• Replace underscores in machine names with hyphens in file names (e.g., my_content_type becomes node--my-content-type.html.twig).
• View mode names also use hyphens (e.g., teaser, full, search-result).
• Template suggestions are case-insensitive on most file systems, but lowercase is the safe convention.