8.5.x theme.api.php hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
8.0.x theme.api.php hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
8.1.x theme.api.php hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
8.2.x theme.api.php hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
8.3.x theme.api.php hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
8.4.x theme.api.php hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
8.6.x theme.api.php hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)

Alters named suggestions for a specific theme hook.

This hook allows any module or theme to provide alternative theme function or 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'].

@todo Add @code sample.

Parameters

array $suggestions: An array of theme suggestions.

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

See also

hook_theme_suggestions_alter()

hook_theme_suggestions_HOOK()

Related topics

11 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.

bartik_theme_suggestions_form_alter in core/themes/bartik/bartik.theme
Implements hook_theme_suggestions_HOOK_alter() for form templates.
test_theme_theme_suggestions_theme_test_function_suggestions_alter in core/modules/system/tests/themes/test_theme/test_theme.theme
Implements hook_theme_suggestions_HOOK_alter().
test_theme_theme_suggestions_theme_test_suggestions_alter in core/modules/system/tests/themes/test_theme/test_theme.theme
Implements hook_theme_suggestions_HOOK_alter().
theme_suggestions_test_theme_suggestions_theme_test_function_suggestions_alter in core/modules/system/tests/modules/theme_suggestions_test/theme_suggestions_test.module
Implements hook_theme_suggestions_HOOK_alter().
theme_suggestions_test_theme_suggestions_theme_test_specific_suggestions_alter in core/modules/system/tests/modules/theme_suggestions_test/theme_suggestions_test.module
Implements hook_theme_suggestions_HOOK_alter().

... See full list

File

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

Code

function hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables) {
  if (empty($variables['header'])) {
    $suggestions[] = 'hookname__' . 'no_header';
  }
}

Comments

flyke’s picture

I used this function to be able to override form templates.
The goal is to be able to copy form.tpl.php (for example from the core classy theme) and place it in my theme in the templates folder renaming it to form--my-custom-form-id.tpl.php

To get this to work I first used:

/**
 * Implements hook_theme_suggestions_HOOK_alter.
 */
function mymodule_theme_suggestions_form_alter(array &$suggestions, array $variables) {

  if (isset($variables['element']) && isset($variables['element']['#type']) && $variables['element']['#type'] == 'form') {
    $original_theme_hook = $variables['theme_hook_original'];
    $suggestions[] = $original_theme_hook . '--' . $variables['element']['#id'];
  }

  return $suggestions;
}

When I cleared the caches and inspected a form, I did see theme suggestions. I copied the name from the suggestion and created my custom form--my-custom-form-id.tpl.php file but Drupal never picked it up.

It took me a while to find out that in your theme_suggestions you MUST use underscores and never hyphens ('-').
So I needed to change my code to:

/**
 * Implements hook_theme_suggestions_HOOK_alter.
 */
function mymodule_theme_suggestions_form_alter(array &$suggestions, array $variables) {

  if (isset($variables['element']) && isset($variables['element']['#type']) && $variables['element']['#type'] == 'form') {
    $original_theme_hook = $variables['theme_hook_original'];
    $suggestions[] = $original_theme_hook . '__' . str_replace('-', '_', $variables['element']['#id']);
  }

  return $suggestions;
}