Twig Template Suggester

Overview

Twig Template Suggester fills the gaps in Drupal core's template suggestion system by providing additional template suggestions for a wide variety of elements that core doesn't support natively. This enables themers to create more specific templates based on context such as regions, view modes, bundles, and entity types.

The module automatically registers template suggestions for blocks (by region, bundle, provider), pages and HTML documents (by node type), users (by role and view mode), fields (by view mode), forms (by form ID and region), containers (by type and context), menus (by region and name), taxonomy terms (by view mode), book trees (by region), and local action links (by route).

As a developer utility, it sets its module weight to 100 to ensure its suggestions are processed last, giving it the final word on template suggestions. It also provides a global {{ base_path }} variable to all templates for convenient asset path construction.

Features

Block template suggestions by region (block--[region].html.twig, block--[region]--[block_id].html.twig)
Block template suggestions by bundle for custom/content blocks (block--bundle--[bundle].html.twig)
Block template suggestions by provider and base plugin with region combinations
HTML and page template suggestions by node type (html--node--[type].html.twig, page--node--[type].html.twig)
User template suggestions by highest role, user ID, and view mode (user--[role]--[view_mode].html.twig)
Field template suggestions by view mode, entity type, and bundle combinations
Form template suggestions by form ID, element ID, and region (form--[form_id].html.twig)
Form element and input template suggestions by element ID and type
Container template suggestions by type, view name/display, managed file fields, and parent status
Menu template suggestions by region and menu name (menu--[region].html.twig)
Taxonomy term template suggestions by view mode and bundle
Book tree template suggestions by region
Menu local action template suggestions by link route
Fix for entity-specific layout templates (workaround for core issue #2881195)
Removes duplicate template suggestions from blocks
Provides {{ base_path }} variable to all templates for asset paths

Use Cases

Region-specific block styling

Create different block styles for each region. For example, blocks in the sidebar might need different styling than blocks in the header. Create templates like block--sidebar.html.twig or block--header.html.twig to target all blocks in specific regions.

Node type-specific page layouts

Apply completely different page layouts for different content types. Create page--node--article.html.twig for articles with a wide content area and page--node--landing_page.html.twig for landing pages with a different structure.

Role-based user profile theming

Display user profiles differently based on user roles. Create user--administrator--full.html.twig for admin profiles or user--member.html.twig for regular members.

View mode-aware field templates

Style the same field differently across view modes. For example, an image field might be large in 'full' view mode but a thumbnail in 'teaser'. Create field--field_image--full.html.twig and field--field_image--teaser.html.twig.

Form styling per form or region

Apply unique styling to specific forms or all forms in a region. Use form--user_login_form.html.twig for the login form, or form--sidebar.html.twig for all forms placed in the sidebar region.

Menu styling by region

Style menus differently based on where they are placed. The main navigation in the header might be horizontal (menu--header.html.twig) while the same menu in a footer could be styled as a vertical list (menu--footer.html.twig).

Taxonomy term view mode templates

Display taxonomy terms differently in different contexts. Create taxonomy_term--tags--full.html.twig for the full term page and taxonomy_term--tags--teaser.html.twig for term listings.

Content type-specific HTML wrappers

Apply different body classes or meta information based on content type. Create html--node--article.html.twig to add specific schema.org markup or tracking codes for articles only.

Tips

Enable Twig debugging during development to see all available template suggestions in your page source HTML comments
Use dashes in template filenames (e.g., block--sidebar--main-menu.html.twig) - they correspond to underscores in suggestion names
The {{ base_path }} variable is available in all templates - useful for referencing theme assets: {{ base_path ~ directory }}/images/logo.svg
For block type-specific templates, consider using the Block Type Templates module alongside Twig Template Suggester for more complete coverage
Template suggestions are ordered by specificity - more specific suggestions appear later and take precedence
Remember that menu region suggestions require the 'region' attribute to be set in your theme's block templates

Related Projects

Display Suite

Optional integration to fix entity-specific layout templates when DS configuration is present. Enable via settings.php: $config['twigsuggest.settings']['alternate_ds_suggestions'] = TRUE;

Webform

Provides container and form element template suggestions for webform elements using #webform_id and #webform_key attributes

Book Core

Provides book_tree template suggestions by region for book navigation blocks

Views Core

Provides container template suggestions for Views embed elements by view name and display ID

Hooks

Hook	Description
`hook_theme_suggestions_block`	Adds template suggestions for blocks based on region, bundle (for content blocks), provider, base plugin, and menu name combinations.
`hook_theme_suggestions_layout_alter`	Fixes entity-specific layout templates by adding double underscores to layout IDs when Display Suite configuration is present. Disabled by default, enable via settings.php.
`hook_theme_suggestions_container`	Adds template suggestions for container elements based on type, view context, managed file wrapping, parent status, group, and webform key.
`hook_theme_suggestions_form_alter`	Adds template suggestions for forms based on element ID, form ID, and region. Supports region-specific form templates when region attribute is set.
`hook_theme_suggestions_form_element`	Adds template suggestions for form elements based on element ID, type, and webform ID.
`hook_theme_suggestions_input`	Adds template suggestions for input elements based on element ID.
`hook_theme_suggestions_user`	Adds template suggestions for user entities based on user ID, view mode, and highest role.
`hook_theme_suggestions_html`	Adds template suggestions for the HTML wrapper based on current node type.
`hook_theme_suggestions_page`	Adds template suggestions for page templates based on current node type.
`hook_theme_suggestions_field`	Adds template suggestions for fields based on view mode, entity type, and bundle combinations.
`hook_theme_suggestions_field_alter`	Adds entity reference target type as a field template suggestion.
`hook_theme_suggestions_taxonomy_term`	Adds template suggestions for taxonomy terms based on view mode, bundle, and term ID.
`hook_theme_suggestions_book_tree`	Adds template suggestions for book trees based on region.
`hook_theme_suggestions_block_alter`	Removes duplicate template suggestions from blocks to keep suggestion lists clean.
`hook_theme_suggestions_menu_alter`	Adds template suggestions for menus based on region, supporting both specific menu and all menus in a region.
`hook_theme_suggestions_menu_local_action_alter`	Adds template suggestions for menu local actions based on the link's route name, building progressively specific suggestions.
`hook_preprocess`	Adds the base_path variable to all templates, enabling easy construction of asset paths in Twig.

Troubleshooting

Template suggestions are not appearing

Ensure Twig debugging is enabled at /admin/config/development/settings. Clear all caches with drush cr. Check page source (not browser inspector) for HTML comments showing available suggestions.

My template is not being used despite matching the suggestion pattern

Verify the template filename exactly matches the suggestion (use underscores in the filename, not hyphens). Ensure the template is in your theme's templates directory. Clear caches after adding new templates.

Block region suggestions not working

Block region suggestions require the block to be placed via the block layout UI (/admin/structure/block). Programmatically rendered blocks may not have region information available.

Display Suite layout fix not working

The layout fix is disabled by default. Enable it in settings.php: $config['twigsuggest.settings']['alternate_ds_suggestions'] = TRUE; Note this may not work for all DS configurations.

Template suggestions from other modules override twigsuggest

Twig Template Suggester sets its module weight to 100 to ensure it runs last. If another module has a higher weight, its suggestions will take precedence. Check module weights in the system.module table.

Twig Template Suggester `twigsuggest`