With our ability to create custom block types and manually add additional fields in Drupal 8, is there a simple naming convention to create block--custom_block_type.html.twig to handle the layout of additional fields?

Example: using theme hook suggestions for content types: node--content_type.html.twig

Are custom block types able to be handled this way without going the module route?

5 Answers 5


Here's one way to do it, in a module or theme:

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

Results in template suggestions like:


The instanceof might be overcautious, take it or leave it.

  • I'm surprised this functionality isn't in core. Aug 30, 2021 at 15:56

This page gives a very good overview of drupal 8 naming conventions, also for custom blocks:

Drupal 8 - Template naming conventions

This page says about block templates:

For example, "block--block--1.html.twig" would be used for the first user-submitted block added from the block administration screen since it was created by the block module with the id of 1. Region-specific block templates are not available in Drupal 8.

If you had a block created by a custom module called "custom" and a delta of "my-block", the theme hook suggestion would be called "block--custom--my-block.html.twig."

Also one more example with Views, if you have a block created by views with a view name "front_news" and display id "block_1" then the theme hook suggestion would be: block--views-block--front-news-block-1.html.twig (notice, when you have underscores in a display id or in a view name - you have to transform them in to a single dash)

Be aware that module names are case sensitive in this context. For instance if your module is called 'MyModule', the most general theme hook suggestion for this module would be "block--MyModule.html.twig."

Hope that helps. Have a nice day.

  • Very familiar with this page. In regards to the block section, it is geared more for creating modules. We understand this process. What I'm looking for is whether or not we can apply .html.twig without having the need for modules. I appreciate the response.
    – webhorse
    Mar 26, 2015 at 16:33
  • 1
    Sorry if I'm misunderstanding, but it looks like you're asking whether you can extend Drupal's default template suggestions without using a module? The answer's yes, but you'll still need to implement hook_theme_suggestions_alter() in a theme. If you're looking for more advanced suggestions already built into core than are listed on the linked page, I think you're out of luck at this time
    – Clive
    Mar 26, 2015 at 16:40
  • @Clive Yes, that is what we're looking to do. Thanks for the response.
    – webhorse
    Mar 26, 2015 at 17:07

@Cottser answer works. I just modified it to keep the right specificity using array_splice, otherwise the bundle type template gets applied later in the chain than block instance suggestions.

$suggestion = 'block__' . $content['#block_content']->bundle();
array_splice( $suggestions, 2, 0, $suggestion );

There is an issue to fix this in core for all entities



A simple/more precise usage with block type along with view mode is as below:

  * Implements hook_theme_suggestions_block_alter()
function hook_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() . '__' . $content['#view_mode'];

Not exactly as you wish, but Yes, you just need to stare it carefully.

*Make sure you have debugging mode on. Refer here to turn it on.

In my case, I have created 'Custom Block Type'

Then created two block of this block type (Just to confirm). Assigned them in a region. Then inspect any one of the block. You can see clearly in attached image, there is a template suggestion(marked red) which is common for both the block.

enter image description here

Not the answer you're looking for? Browse other questions tagged or ask your own question.