function 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, array(
    'node',
    'taxonomy_term',
  ))) {
    $suggestions[] = $hook . '__' . 'logged_in';
  }
}

Parameters

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

hook_theme_suggestions_HOOK_alter()

Related topics

File

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

Hooks and documentation related to the theme and render system.

Code

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()
    ->getId();
}