8.5.x theme.api.php hook_theme_suggestions_HOOK(array $variables)
8.0.x theme.api.php hook_theme_suggestions_HOOK(array $variables)
8.1.x theme.api.php hook_theme_suggestions_HOOK(array $variables)
8.2.x theme.api.php hook_theme_suggestions_HOOK(array $variables)
8.3.x theme.api.php hook_theme_suggestions_HOOK(array $variables)
8.4.x theme.api.php hook_theme_suggestions_HOOK(array $variables)
8.6.x theme.api.php hook_theme_suggestions_HOOK(array $variables)

Provides alternate named suggestions for a specific theme hook.

This hook allows modules to provide alternative theme function or template name suggestions.

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

@todo Add @code sample.


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

Return value

array An array of theme suggestions.

See also


Related topics

29 functions implement hook_theme_suggestions_HOOK()

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.
block_theme_suggestions_block in core/modules/block/block.module
Implements hook_theme_suggestions_HOOK().
forum_theme_suggestions_forums in core/modules/forum/forum.module
Implements hook_theme_suggestions_HOOK().
node_theme_suggestions_node in core/modules/node/node.module
Implements hook_theme_suggestions_HOOK().
search_theme_suggestions_search_result in core/modules/search/search.pages.inc
Implements hook_theme_suggestions_HOOK().

... See full list


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


function hook_theme_suggestions_HOOK(array $variables) {
  $suggestions = array();
  $suggestions[] = 'node__' . $variables['elements']['#langcode'];
  return $suggestions;


bc’s picture

It seems that a suggestion template needs to be provided by a theme/templates directory, and not module/templates.

Alan D.’s picture

When using modules, like Drupal 7, you need to register the theme info for the ones that you define. So if you defined paragraph__test for paragraph--test.html.twig for example

Simply defining the base hook and everything else just seems to work :)

 * Implements hook_theme().
function MODULE_theme() {
 $theme['paragraph__test'] = [
   'base hook' => 'paragraph',

return $theme;
sic’s picture

Add view mode to taxonomy terms:

 * Implements hook_theme_suggestions_HOOK_alter().
function mytheme_theme_suggestions_taxonomy_term_alter(&$suggestions, $variables) {
  $elements = $variables['elements'];

  if (isset($elements['#taxonomy_term']) && isset($elements['#theme']) && isset($elements['#view_mode'])) {
    $term = $elements['#taxonomy_term'];

    if (is_object($term)) {
      $suggestions[] = $elements['#theme'] . '__' . $term->getVocabularyId() . '__' . $elements['#view_mode'];
      $suggestions[] = $elements['#theme'] . '__' . $term->id() . '__' . $elements['#view_mode'];