Twig Template Suggester
Provides extensive template suggestions for Drupal elements that core doesn't cover, enabling precise theming control for blocks, forms, menus, users, taxonomy terms, and more.
twigsuggest
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
Technical Details
Hooks 17
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 5
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.
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 require the block to be placed via the block layout UI (/admin/structure/block). Programmatically rendered blocks may not have region information available.
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.
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.