Twig Template Naming in Drupal 10 Themes

Twig Template Naming in Drupal 10 Themes

By: Anonymous | Published On: Thu, 01/23/2025 - 14:14

Twig templates are files with the .html.twig extension used to define the HTML structure and layout of various components in Drupal. These templates allow developers to customize the look and feel of pages, blocks, nodes, and other elements.

Drupal uses a hierarchical template naming system, making it possible to override templates for specific components, entities, or conditions. By naming templates according to conventions, you can ensure they are applied to the correct contexts.

Twig Template Naming

Twig template files are named following a pattern that corresponds to their scope and specificity. The general naming convention is:

base-name--modifier.html.twig

base-name: Represents the main template type (e.g., page, block, node).

modifier: Provides additional specificity (e.g., node type, block region, or view mode).

.html.twig: The file extension for all Twig templates.

Common Twig Templates in Drupal 10

Here is a list of commonly used Twig templates and their naming variations:

1. Page Templates

Page templates define the overall structure of a page.

• html.html.twig: Base template for the HTML structure.

• page.html.twig: Default page layout.

• page--front.html.twig: Template for the front page.

• page--node--[node-type].html.twig: Template for a specific content type.

2. Node Templates

Node templates define the layout for content entities.

• node.html.twig: Default node template.

• node--[content-type].html.twig: Template for a specific content type.

• node--[content-type]--[view-mode].html.twig: Template for a specific view mode of a content type.

3. Block Templates

Block templates define the structure of blocks.

• block.html.twig: Default block template.

• block--[region].html.twig: Template for blocks in a specific region.

• block--[module-name]-[delta].html.twig: Template for a specific block instance.

4. Views Templates

Views templates define the layout for views and their components.

• views-view.html.twig: Default template for a view.

• views-view--[view-name].html.twig: Template for a specific view.

• views-view--[view-name]--[display-id].html.twig: Template for a specific display in a view.

• views-view-field.html.twig: Template for individual fields in a view.

5. Region Templates

Region templates define the layout for theme regions.

• region.html.twig: Default region template.

• region--[region-name].html.twig: Template for a specific region (e.g., region--header.html.twig).

6. Menu Templates

Menu templates control the layout of navigation menus.

• menu.html.twig: Default menu template.

• menu--[menu-name].html.twig: Template for a specific menu.

7. Field Templates

Field templates define the layout for individual fields.

• field.html.twig: Default field template.

• field--[entity-type]--[field-name].html.twig: Template for a specific field.

• field--[entity-type]--[field-name]--[view-mode].html.twig: Template for a specific field in a specific view mode.

8. Comment Templates

Comment templates define the structure for comments.

• comment.html.twig: Default comment template.

• comment--[node-type].html.twig: Template for comments on a specific content type.

8. Taxonomy terms

Pattern: taxonomy-term--[vocabulary-machine-name|tid].html.twig
Base template: taxonomy-term.html.twig (base location: core/modules/taxonomy/templates/taxonomy-term.html.twig)

Theme hook suggestions are made based on these factors, listed from the most specific template to the least. Drupal will use the most specific template it finds:

• taxonomy-term--[tid].html.twig

• taxonomy-term--[vocabulary-machine-name].html.twig

• taxonomy-term.html.twig

9. Views

All views templates can be overridden with a variety of names, using the view, the display ID of the view, the display type of the view, or some combination thereof.

For each view, there will be a minimum of two templates used. The first is used for all views: views-view.html.twig.

The second template is determined by the style selected for the view. Note that certain aspects of the view can also change which style is used; for example, arguments which provide a summary view might change the style to one of the special summary styles.

The default style for all views is views-view-unformatted.html.twig.

Many styles will then farm out the actual display of each row to a row style; the default row style is views-view-fields.html.twig.

Patterns:

• views-view--[viewid]--[view-display-id].html.twig
• views-view--[viewid]--[view-display-type].html.twig
• views-view--[view-display-type].html.twig
• views-view--[viewid].html.twig
• views-view.html.twig

Overriding Twig Templates

To override a template:

1. Identify the template you want to override.

2. Copy the template file to your theme's templates directory.

3. Rename the file to match the naming convention for your desired specificity.

4. Clear the cache (drush cache:rebuild or via the admin interface) to apply the changes.

Debugging Twig Templates

Enabling Twig debugging can help identify which templates are used and in what order they are suggested. To enable debugging:

1. Edit the services.yml file (e.g., sites/default/services.local.yml).

2. Set the debug parameter under twig.config to true:

   parameters:
     twig.config:
       debug: true
       auto_reload: true
       cache: false

3. Clear the cache.

Debug comments will appear in the HTML source, showing the template hierarchy.