A block is a reusable widget that is placed inside regions (layout containers) of your theme. Blocks can be created, removed, rearranged, and configured in the Block layout administration page. Examples of blocks include the "Who's online" listing, the main navigation menu, and the breadcrumb trail. The main page content is also a block. Each block has its own configuration settings, which allow you to select which pages of your site will display the block.

A module can provide a block using the Plugin API. When a module provides a block, it is listed on the Block layout administrative page and can be placed in a region by a site administrator. Many tools, like Views or menus, have the ability to generate new blocks based on configuration, which can then be placed into regions.

Example tasks

  • Rearrange blocks in a theme by placing them in specific regions
  • Customize the visibility of a block for certain pages or types of pages
  • Provide a block in a module using the Plugin API


The Block layout system underwent many changes and transformations during Drupal 8's development cycle. Be sure to scrutinize or avoid resources that were published before Drupal 8's official release (November 2015), as they can confusingly refer to configuration screens that have since been redesigned. Resources labeled for Drupal 8 should apply to Drupal 9.

Drupalize.Me resources


Drupal 7

Related topics


Blocks in code

Blocks are created using the Plugin API. Any module developer wishing to implement a new block will need to understand how the Plugin API works.


More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources