/Drupal 8

function hook_theme_suggestions_alter

hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)

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.

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

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


array $suggestions: An array of alternate, more specific names for template files or theme functions.

array $variables: An array of variables passed to the theme hook. 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'].

Return value

array An array of theme suggestions.

See also


Related topics

Define functions that alter the behavior of Drupal core.


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


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

© 2001–2016 by the original authors
Licensed under the GNU General Public License, version 2 and later.
Drupal is a registered trademark of Dries Buytaert.