Drupal 9 Entity Template Customization: A Guide to Tailoring Theme Suggestions for Ultimate Design Flexibility

Enhance Drupal templates using Twig template suggestions. Explore Twig template suggestions for Drupal entities and view modes with code snippets in your themeName.theme file.

Content type

Page level suggestions

<?php
/**
 * Implements hook_theme_suggestions_page_alter().
 */
function themeName_theme_suggestions_page_alter(array &$suggestions, array $variables) {
  if ($node = \Drupal::routeMatch()->getParameter('node')) {
    $suggestions[] = 'page__' . $node->bundle();
  }
}

This PHP code implements hook_theme_suggestions_page_alter() in Drupal, providing theme suggestions based on the node bundle for page templates.

Node level suggestions

<?php
/**
 * Implements hook_theme_suggestions_node_alter().
 * Add theme suggestions based on the node bundle.
 */
function themeName_theme_suggestions_node_alter(array &$suggestions, array $variables) {
  if ($node = \Drupal::routeMatch()->getParameter('node')) {
    $suggestions[] = 'node__' . $node->bundle();
  }
}

/**
 * Implements hook_theme_suggestions_HOOK_alter().
 * Add theme suggestions only for authenticated users.
 */
function themeName_theme_suggestions_node_alter(array &$suggestions, array $variables) {
  $logged_in = \Drupal::currentUser()->isAuthenticated();
  if ($logged_in) {
    $suggestions[] = 'node__' . 'authenticated';
  }
}

The provided PHP code defines two hook functions for theme suggestions in Drupal. The first function appends theme suggestions based on the node bundle, allowing more targeted template overrides. The second function adds theme suggestions exclusively for authenticated users, enhancing customization for their viewing experience.

Block type

Suggestions for custom block type

<?php

/**
 * Implements hook_theme_suggestions_HOOK_alter() for block templates.
 */
function themeName_theme_suggestions_block_alter(&$suggestions, $variables) {
  $content = $variables['elements']['content'];

  if (isset($content['#block_content']) && $content['#block_content'] instanceof \Drupal\block_content\BlockContentInterface) {
    $suggestions[] = 'block__' . $content['#block_content']->bundle();
  }
}

Suggestions for custom block types based on the region

<?php
/**
 * Implements hook_theme_suggestions_HOOK_alter() for block templates based on regions.
 */
function themeName_theme_suggestions_block_alter(&$suggestions, $variables) {
  // Region suggestion for blocks in panels.
  if (isset($variables['elements']['#configuration']['region'])) {
    $region = $variables['elements']['#configuration']['region'];
    $suggestions[] = 'block__' . $region;

    if (isset($variables['elements']['#configuration']['provider'])) {
      $provider = $variables['elements']['#configuration']['provider'];
      $suggestions[] = 'block__' . $region . '__' . $provider;
    }
  }

  // Region suggestion for blocks in Drupal.
  if (isset($variables['elements']['#id'])) {
    if ($block = \Drupal\block\Entity\Block::load($variables["elements"]["#id"])) {
      $region = $block->getRegion();
      $base_plugin_id = $variables['elements']['#base_plugin_id'];
      $block_id = $variables['elements']['#id'];

      $suggestions[] = 'block__' . $region;
      $suggestions[] = 'block__' . $region . '__' . $base_plugin_id;
      $suggestions[] = 'block__' . $region . '__' . $block_id;
      $suggestions[] = 'block__' . $region . '__' . $base_plugin_id . '__' . $block_id;
    }
  }
}

Suggestions for custom block types based on view mode

<?php
/**
 * Implements hook_theme_suggestions_HOOK_alter() for block templates.
 */
function themeName_theme_suggestions_block_alter(&$suggestions, $variables) {
  // View mode suggestion for custom blocks.
  if (isset($variables['elements']['#configuration']['view_mode'])) {
    $view_mode = $variables['elements']['#configuration']['view_mode'];
    $suggestions[] = 'block__' . $view_mode;
  } else {
    $view_mode = NULL;
  }

  // Custom Blocks (Bundles and view mode).
  if ($variables['elements']['#base_plugin_id'] === 'block_content'
    && isset($variables['elements']['content']['#block_content'])) {
    // Bundle type.
    $bundle = $variables['elements']['content']['#block_content']->bundle();
    $suggestions[] = 'block__' . $bundle;

    if ($view_mode = $variables['elements']['content']['#view_mode']) {
      $suggestions[] = 'block__' . $bundle . '__' . $view_mode;
      $suggestions[] = 'block__' . $view_mode;
    }
  }
}

Menus

<?php

use Drupal\block\Entity\Block;

/**
 * Implements hook_preprocess_HOOK().
 *
 * Pass block region value to content for use in MYTHEME_theme_suggestions_menu_alter.
 */
function themeName_preprocess_block(&$variables) {
  if (isset($variables['elements']['#id'])) {
    $region = Block::load($variables['elements']['#id'])->getRegion();
    $variables['content']['#attributes']['region'] = $region;
  }
}

/**
 * Implements hook_theme_suggestions_HOOK_alter().
 *
 * Provide region-based menu suggestions.
 */
function themeName_theme_suggestions_menu_alter(&$suggestions, array $variables) {
  if (isset($variables['attributes']['region'])) {
    $suggestions[] = 'menu__' . $variables['menu_name'] . '__' . $variables['attributes']['region'];
  }
}

Taxonomy vocabulary

<?php

use Drupal\taxonomy\Entity\Term;

/**
 * Implements hook_theme_suggestions_HOOK_alter().
 * Provides suggestions based on term vocabulary id for taxonomy term pages.
 */
function THEME_NAME_theme_suggestions_page_alter(&$suggestions, &$vars) {
  // Check if the current route corresponds to a taxonomy term page.
  if (\Drupal::routeMatch()->getRouteName() == 'entity.taxonomy_term.canonical' && $tid = \Drupal::routeMatch()->getRawParameter('taxonomy_term')) {
    // Load the taxonomy term entity using the term id.
    $term = Term::load($tid);

    // Add a suggestion based on the term's vocabulary id.
    $suggestions[] = 'page__taxonomy__' . $term->getVocabularyId();
  }
}

Taxonomy terms

Suggestions for Taxonomy Terms for Drupal 8

<?php

use Drupal\taxonomy\Entity\Term;

/**
 * Implements hook_theme_suggestions_HOOK_alter().
 */
function THEME_NAME_theme_suggestions_page_alter(&$suggestions, &$vars) {
  // Check if the current route is for a taxonomy term entity.
  if (\Drupal::routeMatch()->getRouteName() == 'entity.taxonomy_term.canonical' && $tid = \Drupal::routeMatch()->getRawParameter('taxonomy_term')) {
    // Load the taxonomy term entity.
    $term = Term::load($tid);
    
    // Add a theme suggestion based on the vocabulary ID.
    $suggestions[] = 'page__taxonomy__' . $term->getVocabularyId();
  }
}

Suggestions for Taxonomy Terms for Drupal 9

Views

<?php

use Drupal\views\Views;

/**
 * Implements hook_theme_suggestions_page_alter().
 */
function mythemename_theme_suggestions_page_alter(array &$suggestions, array $variables) {
  // Get the view ID from the current route.
  $view_id = \Drupal::routeMatch()->getParameter('view_id');
  
  // Check if the view ID matches the desired view.
  if ($view_id === 'id_of_the_block_or_page') {
    // Add a custom page template suggestion based on the view name.
    $suggestions[] = 'page__view_name';
  }
}

In case if the above function doesn’t work, here is the default structure

• views-view-field--[viewid]--[view-display-id]--[fieldid].html.twig
• views-view-field--[viewid]--page--[fieldid].html.twig
• views-view-field--block--[fieldid].html.twig
• views-view-field--[fieldid].html.twig
• views-view-field.html.twig

User

<?php
/**
 * Implements hook_theme_suggestions_user_alter().
 * Customizes theme suggestions for user entities based on view mode.
 */
function themeName_theme_suggestions_user_alter(array &$suggestions, array $variables) {
  // Adds view mode-specific suggestions for user templates.
  if ($view_mode = $variables['elements']['#view_mode']) {
    $suggestions[] = 'user__' . $view_mode;
  }
}

Paragraphs

<?php
/**
 * Implements hook_theme_suggestions_HOOK_alter().
 */
function themeName_theme_suggestions_paragraph_alter(array &$suggestions, array $variables) {
  $paragraph = $variables['elements']['#paragraph'];
  $parent = $paragraph->getParentEntity();
  
  if ($parent) {
    $suggestions[] = 'paragraph__' . $parent->bundle() . '__' . $paragraph->bundle();
  }
}

Regions

<?php
/**
 * Implements hook_theme_suggestions_HOOK_alter().
 * Adds a template suggestion based on the region name.
 */

function themeName_theme_suggestions_alter(array &$suggestions, array $variables, $hook) {
  if (isset($variables["attributes"]["region"])) {
    $suggestions[] = $variables["theme_hook_original"] . "__" . $variables["attributes"]["region"];
  }
}

Suggestions for Fields

<?php
/**
 * Implements hook_theme_suggestions_field_alter().
 * Customizes field template suggestions based on field name and view mode.
 */
function themeName_theme_suggestions_field_alter(array &$suggestions, array $variables) {
  $name = $variables['element']['#field_name'];

  // View mode.
  if ($view_mode = $variables['element']['#view_mode']) {
    $suggestions[] = 'field__' . $view_mode;
    $suggestions[] = 'field__' . $view_mode . '__' . $name;
  }
}

Suggestions for Form Templates

<?php
/**
 * Implements hook_theme_suggestions_HOOK_alter() for form templates.
 */
function themeName_theme_suggestions_form_alter(array &$suggestions, array $variables) {
  // Add a custom theme suggestion based on the form_id.
  if ($variables['element']['#form_id'] == 'form_id') {
    $suggestions[] = 'form_id';
  }
}

Suggestions for Form Elements

<?php
/**
 * Implements hook_theme_suggestions_HOOK_alter() for form_element.
 * Adds theme suggestions based on the form element type.
 */
function themeName_theme_suggestions_form_element_alter(&$suggestions, $variables) {
  if (!empty($variables['element']['#type'])) {
    $suggestions[] = 'form_element__' . $variables['element']['#type'];
  }
}

Suggestions for views Exposed Form Filters

<?php
/**
 * Implements hook_theme_suggestions_views_exposed_form_alter().
 * Adjusts theme suggestions for Views exposed forms based on configured theme functions.
 */
function themeName_theme_suggestions_views_exposed_form_alter(array &$suggestions, array $variables) {
  if (isset($variables['form']['#theme'])) {
    // Exclude the base Views exposed form theme function and include others.
    array_pop($variables['form']['#theme']);
    $suggestions = $variables['form']['#theme'] + $suggestions;
  }
}

This PHP code snippet implements the hook_theme_suggestions_views_exposed_form_alter() function in Drupal. It adjusts theme suggestions for Views exposed forms based on configured theme functions. The code removes the base Views exposed form theme function and includes others in the suggestions array.

Suggestions to override the page title block

<?php
/**
 * Implements hook_theme_suggestions_HOOK_alter().
 * Customizes theme suggestions for the page title element.
 */
function themename_theme_suggestions_page_title_alter(array &$suggestions, array $variables) {
  $suggestions[] = 'page_title__custom';
}

This PHP code defines a Drupal hook (hook_theme_suggestions_HOOK_alter()) that alters theme suggestions for the page title element. The custom suggestion 'page_title__custom' is added for further customization.

Comment type

Template structure could be in this method for comment types.

comment--field-name-of-the-comment-field-in-the-content-type--content-type.html.twig

comment--field-name-of-the-comment-field-in-the-content-type.html.twig