Twig Template naming conventions
Drupal loads templates based on certain naming conventions. This allows you to override templates by adding them to your theme and giving them specific names.
After adding a template you must rebuild the cache in order for Drupal to discover your new template.
You can debug Twig templates to figure out which templates are being used to output the markup for any given element. More about Twig debugging here.
This page lists the conventions used for the base html structure, the page, regions, blocks, nodes, fields, and other core components. (It's good to know that it is possible to create custom template name suggestions using function hook_theme_suggestions_HOOK_alter.)
HTML (<head>
template)
The HTML template provides markup for the basic structure of the HTML-page including the <head>
, <title>
and <body>
tags.
Base template: html.html.twig (base location: core/modules/system/templates/html.html.twig)
The following are some examples of how you may override the base template:
- html--[internalviewpath].html.twig
- html--node--[nodeid].html.twig
- html.html.twig
See the html.html.twig API documentation.
Page template
Pattern: page--[front|internal/path].html.twig
Base template: page.html.twig (base location: core/modules/system/templates/page.html.twig)
The suggestions are numerous. The front page takes precedence. The rest is based on the internal path of the current page. The front page can be set at "Administration > Configuration > System > Site information." (http://example.com/admin/config/system/site-information). The front page template is page--front.html.twig.
Do not confuse the internal path with path aliases, which are not accounted for.
The list of suggested template files is in order of specificity based on internal paths. One suggestion is made for every element of the current path, though numeric elements are not carried to subsequent suggestions. For example, "http://www.example.com/node/1/edit" would result in the following suggestions:
- page--node--edit.html.twig
- page--node--1.html.twig
- page--node.html.twig
- page.html.twig
See the page.html.twig API documentation. Also see below for the maintenance page template.
Regions
Pattern: region--[region].html.twig
Base template: region.html.twig (base location: core/modules/system/templates/region.html.twig)
The region template is used when a page region has content, either from the Block system or functions like hook_page_top() or hook_page_bottom(). Possible region names are determined by the theme's .info.yml file.
See the region.html.twig API documentation.
Blocks
Pattern: block--[module|--[delta].html.twig
Base template: block.html.twig (base location: core/modules/block/templates/block.html.twig)
- block--[module]--[delta].html.twig
- block--[module].html.twig
- block.html.twig
"module" being the name of the module and "delta", the internal id assigned to the block by the module.
For example, "block--block--1.html.twig" would be used for the first user-submitted block added from the block administration screen since it was created by the block module with the id of 1. Region-specific block templates are not available in Drupal 8.
If you had a block created by a custom module called "custom" and a delta of "my-block", the theme hook suggestion would be called "block--custom--my-block.html.twig."
Also one more example with Views, if you have a block created by views with a view name "front_news" and display id "block_1" then the theme hook suggestion would be: block--views-block--front-news-block-1.html.twig (notice, when you have underscores in a display id or in a view name - you have to transform them in to a single dash)
Be aware that module names are case sensitive in this context. For instance if your module is called 'MyModule', the most general theme hook suggestion for this module would be "block--MyModule.html.twig."
See the block.html.twig API documentation.
Layout builder blocks
For "custom blocks" created through the layout builder, the following template naming suggestions apply:
- block--inline-block--[block-type].html.twig
- block--inline-block.html.twig
- block--[block-type].html.twig
- block--layout-builder.html.twig
- block.html.twig
Nodes
Pattern: node--[content-type|nodeid]--[viewmode].html.twig
Base template: node.html.twig (base location: core/modules/node/templates/node.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:
- node--[nodeid]--[viewmode].html.twig
- node--[nodeid].html.twig
- node--[content-type]--[viewmode].html.twig
- node--[content-type].html.twig
- node--[viewmode].html.twig
- node.html.twig
Note that underscores (_) in a content type's machine name are replaced by hyphens (-).
See the node.html.twig API documentation.
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
Note that underscores in a vocabulary's machine name are replaced by hyphens.
See the taxonomy-term.html.twig API documentation.
Fields
Pattern: field--[[type|name]|[entity-type]--[field-name|content-type]].html.twig
Base template: field.html.twig (base location: core/modules/system/templates/field.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:
- field--node--[field-name]--[content-type].html.twig
- field--node--[field-name].html.twig
- field--node--[content-type].html.twig
- field--[field-name].html.twig
- field--[field-type].html.twig
- field.html.twig
Note that underscores (_) in a Field's machine name are replaced by hyphens (-). Also remember to include "field-" in custom field names, e.g: field--field-phone.html.twig.
See the field.html.twig API documentation.
Comments
Pattern: comment--[comment-field-name]--[node-type].html.twig
Base template: comment.html.twig (base location: core/modules/comment/templates/comment.html.twig)
Support was added to create comment--[comment-field-name]--[node-type].html.twig files, to format comments of a certain node type differently than other comments in the site. For example, a comment made on an article-type node would be "comment--field-comments--article.html.twig".
See the comment.html.twig API documentation.
Comment wrappers
Pattern: field--node--[comment-field-name]--[content-type].html.twig
Base template: field--comment.html.twig
Forums
Pattern: forums--[[container|topic]--forumID].html.twig
Base template: forums.html.twig (base location: core/modules/forum/templates/forums.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:
For forum containers:
- forums--containers--[forumid].html.twig
- forums--[forumid].html.twig
- forums--containers.html.twig
- forums.html.twig
For forum topics:
- forums--topics--[forumid].html.twig
- forums--[forumid].html.twig
- forums--topics.html.twig
- forums.html.twig
See the API documentation for forums.html.twig.
Maintenance page
Pattern: maintenance-page--[offline].html.twig
Base template: maintenance-page.html.twig (base location: core/modules/system/templates/maintenance-page.html.twig)
This applies when the database fails. Useful for presenting a friendlier page without error messages. Theming the maintenance page must be properly setup first.
See the maintenance-page.html.twig API documentation.
Please note that the maintenance-page--offline.html.twig file is currently not rendering when the database is unavailable. Issue being tracked: #2720109: maintenance-page--offline.html.twig is not picked up when system is offline .
Search result
Pattern: search-result--[search-type].html.twig
Base template: search-result.html.twig (base location: core/modules/search/templates/search-result.html.twig)
search-result.html.twig is the default wrapper for individual search results. Depending on type of search different suggestions are made. For example, "example.com/search/node/Search+Term" would result in "search-result--node.html.twig" being used. Compare that with "example.com/search/user/bob" resulting in "search-result--user.html.twig". Modules can extend search types adding more suggestions of their type.
See the search-result.html.twig API documentation.
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
Base template: views-view.html.twig (base location: core/themes/stable/templates/views/views-view.html.twig)
For example, if we want to override "views-view.html.twig" template for our view, the following template names are valid:
- views-view--[viewid]--[view-display-id].html.twig
- views-view--[viewid]--page.html.twig
- views-view--block.html.twig
- views-view--[viewid].html.twig
- views-view.html.twig
views-view-field.html.twig based patterns are postfixed with the view's field id (as in replacement patterns) to display a single field in a view:
- views-view-field--[viewid]--[view-display-id]--[fieldid].html.twig
- views-view-field--[viewid]--page--[fieldid].html.twig
- views-view-field--block--[fieldid].html.twig
- views-view-field--[fieldid].html.twig
- views-view-field.html.twig
Likewise, tables are postfixed with the id:
- views-view-table--[viewid].html.twig
Here is an example of all the templates that will be tried in the following case:
View, named foobar. Style: unformatted. Row style: Fields. Display: Page.
- views-view--foobar--page.html.twig
- views-view--page.html.twig
- views-view--foobar.html.twig
- views-view.html.twig
- views-view-unformatted--foobar--page.html.twig
- views-view-unformatted--page.html.twig
- views-view-unformatted--foobar.html.twig
- views-view-unformatted.html.twig
All fields:
- views-view-fields--foobar--page.html.twig
- views-view-fields--page.html.twig
- views-view-fields--foobar.html.twig
- views-view-fields.html.twig
Single field:
- views-view-field--foobar--page--[fieldid].html.twig
- views-view-field--foobar--[fieldid].html.twig
- views-view-field.html.twig
Media
Base template: media.html.twig
(base location: core/modules/media/templates/media.html.twig
).
- media--source-[source-id].html.twig
- media--[media-type]--[view-mode].html.twig
- media--[media-type].html.twig
- media--[view-mode].html.twig
- media.html.twig
Popular contributed modules
Below are links to template naming conventions documentation pages for popular contributed modules:
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion