function hook_theme_suggestions_HOOK

Same name and namespace in other branches
  1. 9 core/lib/Drupal/Core/Render/theme.api.php \hook_theme_suggestions_HOOK()
  2. 8.9.x core/lib/Drupal/Core/Render/theme.api.php \hook_theme_suggestions_HOOK()
  3. 10 core/lib/Drupal/Core/Render/theme.api.php \hook_theme_suggestions_HOOK()

Provides alternate named suggestions for a specific theme hook.

This hook allows modules to provide alternative theme template name suggestions.

HOOK is the least-specific version of the hook being called. For example, if '#theme' => 'node__article' is called, then hook_theme_suggestions_node() will be invoked, not hook_theme_suggestions_node__article(). The specific hook called (in this case 'node__article') is available in $variables['theme_hook_original'].

Implementations of this hook must be placed in *.module or *.theme files, or must otherwise make sure that the hook implementation is available at any given time.

Suggestions must begin with the value of HOOK, followed by two underscores to be discoverable.

In the following example, we provide suggestions to node templates based bundle, id, and view mode.

function node_theme_suggestions_node(array $variables) {
    $suggestions = [];
    $node = $variables['elements']['#node'];
    $sanitized_view_mode = strtr($variables['elements']['#view_mode'], '.', '_');
    $suggestions[] = 'node__' . $sanitized_view_mode;
    $suggestions[] = 'node__' . $node->bundle();
    $suggestions[] = 'node__' . $node->bundle() . '__' . $sanitized_view_mode;
    $suggestions[] = 'node__' . $node->id();
    $suggestions[] = 'node__' . $node->id() . '__' . $sanitized_view_mode;
    return $suggestions;


array $variables: An array of variables passed to the theme hook. Note that this hook is invoked before any preprocessing.

Return value

array An array of theme suggestions.

See also


Related topics

39 functions implement hook_theme_suggestions_HOOK()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

big_pipe_theme_suggestions_big_pipe_interface_preview in core/modules/big_pipe/big_pipe.module
Implements hook_theme_suggestions_HOOK().
block_content_theme_suggestions_block_alter in core/modules/block_content/block_content.module
Implements hook_theme_suggestions_HOOK_alter() for block templates.
block_theme_suggestions_block in core/modules/block/block.module
Implements hook_theme_suggestions_HOOK().
claro_theme_suggestions_details_alter in core/themes/claro/claro.theme
Implements hook_theme_suggestions_HOOK_alter() for details.
claro_theme_suggestions_form_element_alter in core/themes/claro/claro.theme
Implements hook_theme_suggestions_HOOK_alter() for form_element.

... See full list


core/lib/Drupal/Core/Render/theme.api.php, line 660


function hook_theme_suggestions_HOOK(array $variables) {
    $suggestions = [];
    $suggestions[] = 'hookname__' . $variables['elements']['#langcode'];
    return $suggestions;

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.