Working with Twig templates

Drupal allows you to override all templates used to generate HTML markup, so you can fully control the output markup in your custom theme. There are templates for every part of the page, from the high-level HTML down to small fields.

Overriding Templates

You can override Drupal core templates by adding templates to your theme folder that follow specific naming conventions.

To override templates, you need to:

1. Locate the template you want to override.
2. Copy the template file from its base location into your theme folder.
3. (Optional) Rename the template according to naming conventions to target a more specific subset of use cases.
4. Modify the template as desired.

Once you copy the template file into your theme and clear the cache, Drupal will use your instance of the template file instead of the core version.

You can find out which templates are used for any part of the page using Twig debug tools.

Theme Hook Suggestions

Sometimes you want to modify a template file, but only in certain contexts. A common example is modifying the node template file for only one content type. Drupal's theme layer lets you target specific template use cases by following naming conventions. When rendering an article node, Drupal first looks for node--article.html.twig and uses it if it exists. If not, it falls back to node.html.twig. The process of determining which template names Drupal might use is called theme hook suggestions.

Theme hook suggestions let you implement targeted overrides in your theme for template files using specific naming conventions.

All layers—from core, modules, theme engines, and themes—can provide suggestions. You can add or modify suggestions using the following hooks:

• hook_theme_suggestions_HOOK(array $variables)
• hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
• hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)

Rebuild Cache

When working with theme hook suggestions, there's a chance Drupal is using its cache instead of recognizing new templates. Clear the cache if you encounter this issue. To do so, follow one of the methods described in Drupal's cache clearing guide.

Source Information

You can think of suggestions as naming hints that help the system choose based on the correct conditions.

Template suggestions are set through theme suggestion hooks, which can be altered. These hooks let any module or theme offer alternative theme functions or template name suggestions and reorder or remove suggestions made by hook_theme_suggestions_HOOK() or previous hook calls.

How Drupal Determines Page Template Suggestions Based on Path

This explanation is based on the function theme_get_suggestions():

The list of possible templates for a given page is generated by Drupal using theme_get_suggestions(), which is called by system_theme_suggestions_page().

The page path is broken into components. As noted, the Drupal path is not any of its aliases: for the page, there is one and only one Drupal path. For examples "http://www.example.com/node/1/edit" and "http://www.example.com/mysitename?q=node/1/edit", the Drupal path is node/1/edit, and its components are "node", 1, and "edit".

The prefix is set to “page”. Then the following logic is applied for each component:

1. If the component is numeric, add prefix + “__%” to the list of suggestions.
2. Regardless of numeric or not, add prefix + “__” + component to the list.
3. If the component is not numeric, add “__” + component to the prefix.

After iterating through components, if the page is the front page (as set under "Administration > Configuration > System > Site information."), then “page__front” is added to the suggestions list.

To form actual template filenames, “__” becomes “-”, and “.html.twig” is appended. So for node/1/edit, the suggestion list is:

1. page.html.twig (always included)
2. page--node.html.twig (prefix becomes page__node)
3. page--node--%.html.twig
4. page--node--1.html.twig (prefix unchanged as component is numeric)
5. page--node--edit.html.twig (prefix becomes page__node__edit)
6. page--front.html.twig (only if node/1/edit is the front page)

When rendering the page, the last suggestion is checked first. If it exists, it's used. If not, the next suggestion is checked, and so on. If no specific suggestions exist, page.html.twig is used. This also explains why page--front.html.twig overrides any other suggestion for the front page—it’s always the last suggestion when a page is marked as front.

Differences from Drupal 7

Previously, to change template suggestions, you modified $variables['theme_hook_suggestion'] and $variables['theme_hook_suggestions'] in preprocess functions to inject suggestions. In Drupal 8, modules and themes define and alter theme suggestions using dedicated suggestion hooks.

More Information

See the change notice New hooks for theme suggestions