This project is not covered by Drupal’s security advisory policy.
Lets other modules add extra Twig template names, including for content nested inside a parent (a menu inside a block, a field inside a form). Names use the values only, like core node--page.html.twig. This module does not rewrite #theme.
This is an API. It does not add suggestions on its own. A host module decides what to collect and which children inherit those names. Enable this module, then enable a host. Themes use the host, not this API.
Features
Basic function. A host collects values (for example a region footer_first). This module builds every combination and offers them as theme suggestions on the current hook, or on nested children while that host is rendering.
What enabling it adds.
ThemeSuggestionFrameplugins. A host names the preprocess hook and chooses which children inherit the collected values.skipon a frame, so small hooks such asimageorform_elementdo not inherit that parent. Providers that target those hooks still run.ThemeSuggestionProviderplugins. A host adds one kind of value at a time (region, plugin id, node type). A provider can target theme hooks, frame classes, or both.- Every combination of collected values becomes a template name. Kind labels are not printed. You get
menu--social--footer-first.html.twig, not a name that includesregion.
When to use it. Use this when you are writing a host module (block, later form or paragraph) and you want extra template names without a custom preprocess in the theme.
Example use cases.
- A block host that lets the menu inside a block use a different template by region and node type.
- A later form host that lets
inputorform_elementuse a different template by form id.
Post-Installation
There is no settings page.
- Enable Theme Suggestions API.
- Enable a host module that uses this API.
- Add templates in your theme using the names the host documents.
Additional Requirements
- Drupal 11.4 or later, or Drupal 12
- PHP 8.3 or later (Drupal 12 sites already require PHP 8.5)
Similar projects
Entity Theme Suggestions is entity-only and unmaintained. This API works with any theme hook and is plugin-based.
Supporting this Module
File bug reports and feature requests in the issue queue.
Community Documentation
See the README in the Git repository for ThemeSuggestionFrame, ThemeSuggestionProvider, and how a host wires them.
Project information
- Project categories: Developer tools
- Created by samerali on , updated
This project is not covered by the security advisory policy.
Use at your own risk! It may have publicly disclosed vulnerabilities.
