How to Create a Custom Block in Drupal

Summary

Learn how to create a custom block in Drupal using the Block module. This guide covers both the user interface method and the programmatic approach using a custom module.

Introduction

Blocks in Drupal are reusable content containers that can be placed in different regions of a website. Creating a custom block allows you to add dynamic or static content to specific areas of your site, such as sidebars or headers.

Drupal also provides Custom Block Types out of the box, which allow site builders to create different types of reusable blocks with custom fields. These can be managed through Structure > Block Layout > Custom Block Library.

Creating a Custom Block via UI

If you prefer a no-code approach, you can create a block through the Drupal admin interface.

1. Navigate to Structure > Block Layout (/admin/structure/block).
2. Click on the Custom block library tab.
3. Click Add custom block.
4. Enter a Block Description and the content you want to display.
5. Click Save and then place the block in a region using the Block Layout page.

Creating a Custom Block Programmatically

For more flexibility, you can define a custom block in a module. In the example below, we will print the site name and another variable in a custom twig template file for a custom block.

Step 1: Create a Custom Module

1. Navigate to modules/custom/ and create a folder (e.g., custom_blocks).
2. Inside, create a custom_blocks.info.yml file:

name: 'Custom Blocks'
type: module
description: 'Provides custom blocks.'
core_version_requirement: ^8 || ^9 || ^10
package: Custom

Step 2: Define the Custom Block

Create a PHP file inside src/Plugin/Block/ (e.g., ExampleBlock.php):

<?php
namespace Drupal\custom_blocks\Plugin\Block;
use Drupal\Core\Block\BlockBase;
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;
use Drupal\Core\Config\ConfigFactoryInterface;
/**
 * Provides an 'Example' Block.
 *
 * @Block(
 *   id = "example_block",
 *   admin_label = @Translation("Example Block"),
 * )
 */
class ExampleBlock extends BlockBase implements ContainerFactoryPluginInterface {
  protected $configFactory;
  /**
   * Constructs a new ExampleBlock.
   */
  public function __construct(array $configuration, $plugin_id, $plugin_definition, ConfigFactoryInterface $config_factory) {
    parent::__construct($configuration, $plugin_id, $plugin_definition);
    $this->configFactory = $config_factory;
  }
  /**
   * {@inheritdoc}
   */
  public function build() {
    $site_name = $this->configFactory->get('system.site')->get('name');
    return [
      '#theme' => 'example_block',
      '#site_name' => $site_name,
      '#message' => $this->t('Hello, this is a custom block!'),
      '#cache' => [
        'max-age' => 3600,
      ],
    ];
  }
  /**
   * {@inheritdoc}
   */
  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
    return new static(
      $configuration,
      $plugin_id,
      $plugin_definition,
      $container->get('config.factory')
    );
  }
}

Step 3: Define the Theme Hook

Create a custom_blocks.module file at the root of the module with the following content:

<?php
function custom_blocks_theme($existing, $type, $theme, $path): array {
  return [
    'example_block' => [
        'variables' => [
            'site_name' => NULL,
            'message' => NULL,
        ]
     ],
  ];
}

Step 4: Define the Twig Template

Create a Twig file in your theme or module at templates/example-block.html.twig:

<div class="custom-block"> <h2>{{ site_name }}</h2> <p>{{ message }}</p> </div>

Step 5: Clear Cache & Enable the Module

1. Run drush cr or clear cache manually (/admin/config/development/performance).
2. Enable the module via Extend (/admin/modules).

See the screenshot of how it will look like:

Step 6: Place the Block

1. Navigate to Structure > Block Layout (/admin/structure/block).
2. Click Place block, search for "Example Block" and assign it to a region.
3. Click Save.

Conclusion

Creating a custom block in Drupal allows you to add dynamic or static content easily. Whether using the UI or a custom module, blocks offer flexibility in displaying content across your site.

If you need further help or custom code solutions, feel free to reach out via our Contact Us page. We're happy to assist!