Theme Suggestions API

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.

• ThemeSuggestionFrame plugins. A host names the preprocess hook and chooses which children inherit the collected values.
• skip on a frame, so small hooks such as image or form_element do not inherit that parent. Providers that target those hooks still run.
• ThemeSuggestionProvider plugins. 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 includes region.

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 input or form_element use a different template by form id.

Post-Installation

There is no settings page.

1. Enable Theme Suggestions API.
2. Enable a host module that uses this API.
3. 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.