How to get a twig template suggestion for a custom block?

Template custom blocks

With Drupal, you can create custom block types. You can add the necessary fields such as a text field, image, etc. exactly like for the nodes. This can be useful, for example, to create a “hero” block with an image that takes up the entire width of the site with text displayed on the image. We can then create several blocks from this type of block and integrate them into one or more positions defined by the template.

On the other hand, when we want to create a branch template to create a template for this custom block, when we activate debug mode, we do not see a suggestion for the block type. Drupal offers a suggestion for a specific block. This means that if we have several custom blocks created from the same type of block, we will have several templates with the same code. So this is not an ideal solution. The code will not be easy to maintain and we needlessly repeat templates.

Native template suggestion for a block

FILE NAME SUGGESTIONS:
   * block--illustration2.html.twig
   * block--block-content--4ba32eec-399d-464b-8b12-717a837a557b.html.twig
   * block--block-content.html.twig
   * block--block-content.html.twig
   * block.html.twig

In this example, block--illustration2.html.twig corresponds to a single block. If we have several blocks that are created from the same type of block, we will have different suggestions like block--illustration1.html.twig, etc.

There is a very simple solution to get a template suggestion. Simply add this code to your *.theme file and implement the hook_theme_suggestions_hook() hook

Implementing hook_theme_suggestions_hook()

/**
 * Implementing hook_theme_suggestions_hook()
 */
function MY_THEME_theme_suggestions_block_alter(&$suggestions, $variables) {
  if (isset($variables['elements']['content']['#block_content'])) {
    $bundle = $variables['elements']['content']['#block_content']->bundle();
    array_splice($suggestions, 1, 0, 'block__' . $bundle);
  }
}

With this hook, you get a branch template suggestion for each block type.

Template suggestion with hook

FILE NAME SUGGESTIONS:
   * block--illustration2.html.twig
   * block--block-content--4ba32eec-399d-464b-8b12-717a837a557b.html.twig
   * block--block-content.html.twig
   x block--bloc-rounded-image.html.twig
   * block--block-content.html.twig
   * block.html.twig

We now have a suggestion for the block type, for example block--bloc-rounded-image.html.twig for a block type whose ID is bloc_rounded_image.

We can therefore create a twig template called block--bloc-rounded-image.html.twig and code the html structure with the Drupal fields as we would for a node.

Twig template example

<div class="hero">

    {{ content.field_image_1 }}

    <div class="hero-txt">{{ content.field_txt_1 }}</div>

</div>