Site Building

Blocks for Drupal 7, 8, 9, and 10

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


Blocks are stable in Drupal core.

Drupalize.Me resources

More information

Overview of regions from a theming perspective.

Drupal 8, 9, and 10
More information

Themes define the regions that are available for site administrators to place blocks in, creating a layout framework within which the components that compose a page can be placed. As a theme developer you'll need to determine what regions are necessary to accommodate your design's layout, while also ensuring it'll work with the way Drupal uses blocks to place content onto the page. Deciding what regions to create requires knowledge of how Drupal works and a clear vision of the design you're trying to achieve.

In this tutorial we'll:

  • Explain what regions are and how they relate to themes
  • Describe how regions are handled internally within Drupal
  • Demonstrate things to keep in mind when planning the regions for your custom theme

By the end of this tutorial you should be able to describe what a region is, explain how Drupal themes use regions to place content, and get started dissecting your own designs into regions.

Drupal 8, 9, and 10

Drupal 7

More information

In this chapter Michelle will explain what blocks are and how we can use them on our site. We'll look at the demo regions where we can place our blocks, and move some things around. We'll also look at creating our own simple custom block, along with covering the ways that we can change the visibility settings.

Related topics


Drupal 7, 8, 9, and 10
More information

A layout can describe how various components are arranged on various levels—from an entire page from the header to the footer, to just the “middle” where the dynamic content goes, to individual components. It can apply to templates for managed content or one-off designs for landing pages.

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.

Drupal 8, 9, and 10
More information

The Drupal plugin system allows a particular module or subsystem to provide functionality in an extensible, object-oriented way. The controlling module defines the basic framework (interface) for the functionality, and other modules can create plugins (implementing the interface) with particular behaviors. Plugins are grouped into plugin types. Each plugin type is managed by a plugin manager service, which uses a plugin discovery method to discover provided plugins of that type and instantiate them using a plugin factory.

The system aims to make it easy for developers to allow for management of these components via the user interface, giving more flexibility and control to site administrators.

In this tutorial we'll take a high-level look at the problem the Plugin API is solving and provide a starting point for diving deeper into the various components that make up the Plugin API.


Not sure where to start? Our guides provide useful learning tracks for all skill levels.

Navigate guides

External resources