Same name and namespace in other branches
  1. 8.9.x core/lib/Drupal/Core/Render/theme.api.php \hook_theme_suggestions_HOOK()
  2. 9 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;
}

Parameters

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

hook_theme_suggestions_HOOK_alter()

Related topics

33 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

File

core/lib/Drupal/Core/Render/theme.api.php, line 660
Hooks and documentation related to the theme and render system.

Code

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