Programmatically building custom blocks in Drupal 8/9

lakshmi , Credit to  volkotech-solutions Jun 02

In Drupal 8/9, custom blocks can be created programmatically using PHP and the Drupal API, allowing for dynamic block generation and integration into the site.

Blocks in Drupal 8/9 are made up of two distinct APIs. The Block Plugin API is a reusable API, and the Block Entity API is used to control block placement and visibility.

In Drupal 8/9, there are three steps to creating a custom block.

  1. Create a custom module in drupal.
  2. Using Annotations, create a block plugin.
  3. Finally, Place the Block to show the content in a particular region.

Create a custom module: 

Modules in Drupal are located in the /modules folder. We'll create two custom and contrib folders inside the /modules folder. Additional modules from will be stored in the contrib folder, and our custom modules will be stored in the custom folder.

Create a .info.yml file:

Let's name our custom module simple_message_block. Create the folder /modules/custom/simple_message_block. In this folder, we'll need to create the file and add the following code.

name: Simple Message Block
description: Display a simple message.
type: module
core_version_requirement: ^8 || ^9

Enable a module:

For all possible ways to enable a module click here.

Using the Manage administrative menu, navigate to the Extend page in the list of modules, search the Simple Message Block module and then select its checkbox. Scroll down to the bottom of the webpage, and then click Install.

simple message

Module Simple Message Block has been enabled successfully.

create a block plugin:

Create SimpleMessage.php should be placed in the modules/custom/simple_message_block/src/Plugin/Block folder structure and add the code below.


namespace Drupal\simple_message_block\Plugin\Block;

use Drupal\Core\Block\BlockBase;

* Provides a 'Simple message' Block.
* @Block(
*   id = "simple_message_block",
*   admin_label = @Translation("Simple message block"),
*   category = @Translation("custom block example"),
* )
class SimpleMessage extends BlockBase {

  * {@inheritdoc}
 public function build() {
   return [
     '#markup' => $this->t('This simple message coming from custom block'),


  • id: machine-readable ID of the block.
  • admin_label: human-readable name of the block.
  • Category: which section belongs to the block listing page.

After creating this file, clear the Drupal site cache to recognize this new class.

The structure of the custom Block module:

custom block

Place the Block  in a particular region:

Next place the custom Block module in any regions are presented in drupal 8/9.Naviagte to      Structure -> Block Layout -> click “place block” icon -> select your block name (simple message) -> select region (for example “Sidebar second” region ) -> save block.



That's all! You have successfully created your first Drupal 8/9 custom simple message block. This was a very simple example of the custom block feature. You can create blocks of specific types of content and place them in any region to create blocks of any type. There are many options and the customization is seemingly endless.