Views templates

Views templates are the Twig files that Drupal uses to build the HTML of a View: the outer wrapper, the list, grid or table, each row and each field. The Views module ships a default for every part. To change the markup, you copy a template into your theme and edit the copy, so the change survives core updates.

How Views templates work in Drupal 11

A view is rendered in layers, and each layer has its own template. Core's Views module provides, among others:

• views-view.html.twig: the whole view. It prints the title, header, exposed filter form, rows, pager, footer and feed icons.
• views-view-unformatted.html.twig, views-view-table.html.twig, views-view-list.html.twig and views-view-grid.html.twig: the format, which wraps the rows.
• views-view-fields.html.twig and views-view-field.html.twig: one row's fields, and a single field.

Each template has a theme hook name, such as views_view_unformatted. The method ViewExecutable::buildThemeFunctions() turns that name into a list of more specific suggestions. For a view with the ID blog and a display ID page_1, whose display plugin is page, the order is:

1. views_view_unformatted__blog__page_1
2. views_view_unformatted__page_1
3. one suggestion per tag of the view
4. views_view_unformatted__blog__page
5. views_view_unformatted__page
6. views_view_unformatted__blog
7. views_view_unformatted

In a file name, each underscore becomes a hyphen, so a double underscore becomes two hyphens. The first suggestion that matches a file in your theme wins.

Example

To wrap each row of the blog view in an article element, copy views-view-unformatted.html.twig from core/modules/views/templates into your theme, for example themes/custom/mytheme/templates/views-view-unformatted--blog.html.twig, and edit it:

{% if title %}
          <h3>{{ title }}</h3>
        {% endif %}
        {% for row in rows %}
          <article{{ row.attributes.addClass('views-row') }}>
            {{- row.content -}}
          </article>
        {% endfor %}

Then run drush cr.

Common mistakes

• Editing the core file. The next core update overwrites it. Always override in the theme.
• Guessing the file name. Use Twig debug mode. In Drupal 11 you can switch on Twig development mode on the Development settings page (/admin/config/development/settings), or set debug: true under twig.config in development.services.yml.
• Leaving debug on in production. The Drupal.org documentation says it should not be enabled there, and it can break parts of the site, especially Views.
• Skipping the cache rebuild. Drupal does not see a new template file until the cache is cleared.

For marketing and content teams

A template is a developer task, and it is only needed for markup. If you want a different order, other fields or a filter, ask for a change to the view's settings instead; that is faster and needs no code. When you do need new markup, tell your developer the view name and which display shows it, because a suggestion can target one display only.

Sources

• Drupal.org: Twig template naming conventions
• Drupal.org: Working with Twig templates
• Drupal.org: Debugging Twig templates
• ViewExecutable::buildThemeFunctions, Drupal core 11.4.x
• views-view.html.twig, Drupal core 11.4.x
• views-view-unformatted.html.twig, Drupal core 11.4.x
• TwigThemeEngine.php, Drupal core 11.4.x