function hook_theme_suggestions_alter

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

Alters named suggestions for all theme hooks.

This hook is invoked for all theme hooks, if you are targeting a specific theme hook it's best to use hook_theme_suggestions_HOOK_alter().

The call order is as follows: all existing suggestion alter functions are called for module A, then all for module B, etc., followed by all for any base theme(s), and finally for the active theme. The order is determined by system weight, then by extension (module or theme) name.

Within each module or theme, suggestion alter hooks are called in the following order: first, hook_theme_suggestions_alter(); second, hook_theme_suggestions_HOOK_alter(). So, for each module or theme, the more general hooks are called first followed by the more specific.

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

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

function MY_MODULE_theme_suggestions_alter(array &$suggestions, array &$variables, $hook) {
    if (\Drupal::currentUser()->isAuthenticated() && in_array($hook, [
    ])) {
        $suggestions[] = $hook . '__' . 'logged_in';


array &$suggestions: An array of alternate, more specific names for template files, 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 variable preprocessing.

string $hook: The base hook name. For example, if '#theme' => 'node__article' is called, then $hook will be 'node', not 'node__article'. The specific hook called (in this case 'node__article') is available in $variables['theme_hook_original'].

See also


Related topics

3 functions implement hook_theme_suggestions_alter()

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

test_theme_theme_suggestions_alter in core/modules/system/tests/themes/test_theme/test_theme.theme
Implements hook_theme_suggestions_alter().
theme_suggestions_test_theme_suggestions_alter in core/modules/system/tests/modules/theme_suggestions_test/theme_suggestions_test.module
Implements hook_theme_suggestions_alter().
theme_test_theme_suggestions_alter in core/modules/system/tests/modules/theme_test/theme_test.module
Implements hook_theme_suggestions_alter().


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


function hook_theme_suggestions_alter(array &$suggestions, array &$variables, $hook) {
    // Add an interface-language specific suggestion to all theme hooks.
    $suggestions[] = $hook . '__' . \Drupal::languageManager()->getCurrentLanguage()

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