8.5.x block.module template_preprocess_block(&$variables)
8.0.x block.module template_preprocess_block(&$variables)
8.1.x block.module template_preprocess_block(&$variables)
8.2.x block.module template_preprocess_block(&$variables)
8.3.x block.module template_preprocess_block(&$variables)
8.4.x block.module template_preprocess_block(&$variables)
8.6.x block.module template_preprocess_block(&$variables)
6.x theme.inc template_preprocess_block(&$variables)
7.x block.module template_preprocess_block(&$variables)

Prepares variables for block templates.

Default template: block.html.twig.

Prepares the values passed to the theme_block function to be passed into a pluggable template engine. Uses block properties to generate a series of template file suggestions. If none are found, the default block.html.twig is used.

Most themes use their own copy of block.html.twig. The default is located inside "core/modules/block/templates/block.html.twig". Look in there for the full list of available variables.


array $variables: An associative array containing:

  • elements: An associative array containing the properties of the element. Properties used: #block, #configuration, #children, #plugin_id.


core/modules/block/block.module, line 214
Controls the visual building blocks a page is constructed with.


function template_preprocess_block(&$variables) {
  $variables['configuration'] = $variables['elements']['#configuration'];
  $variables['plugin_id'] = $variables['elements']['#plugin_id'];
  $variables['base_plugin_id'] = $variables['elements']['#base_plugin_id'];
  $variables['derivative_plugin_id'] = $variables['elements']['#derivative_plugin_id'];
  $variables['label'] = !empty($variables['configuration']['label_display']) ? $variables['configuration']['label'] : '';
  $variables['content'] = $variables['elements']['content'];

  // A block's label is configuration: it is static. Allow dynamic labels to be
  // set in the render array.
  if (isset($variables['elements']['content']['#title']) && !empty($variables['configuration']['label_display'])) {
    $variables['label'] = $variables['elements']['content']['#title'];

  // Create a valid HTML ID and make sure it is unique.
  if (!empty($variables['elements']['#id'])) {
    $variables['attributes']['id'] = Html::getUniqueId('block-' . $variables['elements']['#id']);

  // Proactively add aria-describedby if possible to improve accessibility.
  if ($variables['label'] && isset($variables['attributes']['role'])) {
    $variables['title_attributes']['id'] = Html::getUniqueId($variables['label']);
    $variables['attributes']['aria-describedby'] = $variables['title_attributes']['id'];


chrissnyder’s picture

This hook does not work on blocks that are formatted as a rendered entity when referenced from a field.

mstrelan’s picture

Is it possible to detect the block region and add classes based on region?

sqndr’s picture

I was wondering the same thing. Haven't find a solution for this so far …

sqndr’s picture

I think will do … not sure if this is the way to go though, but it works.

function {theme}_preprocess_block(&$variables) {
  $block_id = $variables['elements']['#id'];
  $block = \Drupal\block\Entity\Block::load($block_id);
  $region = $block->getRegion();

  switch ($region) {
    case 'sidebar_left':
      $variables['attributes']['class'][] = 'block';
      $variables['attributes']['class'][] = '--filled-info';
      $variables['title_attributes']['class'][] = 'block__title';
      $variables['content_attributes']['class'][] = 'block__content';
mortendk’s picture

always pass variables to the template so it can be used in the template to generate the css selectors, hardcoding css classnames is a bad practice.


// Add a region variable to a block.
function vanilla_preprocess_block(&$variables, $hook) {
  $block_id = $variables['elements']['#id'];
  $block = \Drupal\block\Entity\Block::load($block_id);

  $variables['region'] = $block->getRegion();


  set classes = [
    region =='header' ? 'green' : 'blue--cause-im-not-in-header-region',

By using the region as a variable you can test on it from the template & make the theming life so much easier

squall3d’s picture

Alternatively, if you want a use a specific twig template for a region, you can use hook_theme_suggestions_block_alter:

function [your theme]_theme_suggestions_block_alter(array &$suggestions, array $variables) {
  if ($variables['elements']['#configuration']['region']) {
    $suggestions[] = 'block__block_content__' . $variables['elements']['#configuration']['region'];