function hook_theme_suggestions_HOOK_alter

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

Alters named suggestions for a specific theme hook.

This hook allows any module or theme to provide alternative template name suggestions and reorder or remove suggestions provided by hook_theme_suggestions_HOOK() or by earlier invocations of this hook.

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

New suggestions must begin with the value of HOOK, followed by two underscores to be discoverable. For example, consider the below suggestions from hook_theme_suggestions_node_alter:

  • node__article is valid
  • node__article__custom_template is valid
  • node--article is invalid
  • article__custom_template is invalid

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.

In the following example, we provide an alternative template suggestion to node templates based on the user being logged in.

function MY_MODULE_theme_suggestions_node_alter(array &$suggestions, array $variables) {
    if (\Drupal::currentUser()->isAuthenticated()) {
        $suggestions[] = 'node__logged_in';


array $suggestions: An array of theme suggestions, passed by reference.

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

See also



Related topics

18 functions implement hook_theme_suggestions_HOOK_alter()

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

block_content_theme_suggestions_block_alter in core/modules/block_content/block_content.module
Implements hook_theme_suggestions_HOOK_alter() for block templates.
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.
claro_theme_suggestions_maintenance_page_alter in core/themes/claro/claro.theme
Implements hook_theme_suggestions_maintenance_page_alter().
layout_builder_theme_suggestions_field_alter in core/modules/layout_builder/layout_builder.module
Implements hook_theme_suggestions_HOOK_alter().

... See full list


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


function hook_theme_suggestions_HOOK_alter(array &$suggestions, array &$variables) {
    if (empty($variables['header'])) {
        $suggestions[] = 'hookname__no_header';

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