Block

In Drupal a block is a reusable unit of page output, from a module or written as a content block, that you place per theme and limit by page or role.

Learn DrupalDrupal glossary Last updated

A block is a piece of output that you place in a theme region, such as a menu, a search form, a breadcrumb trail or a box of text. Technically it is a block plugin supplied by a module, placed through a configuration entity that stores the theme, region, weight and visibility rules. The main page content counts as a block too.

How blocks work in Drupal 11

Modules provide block plugins. A plugin class carries a #[Block] attribute with an id and an admin_label. The Breadcrumbs block, for example, is system_breadcrumb_block. Writing your own is part of the Plugin API.

A placed block is a block configuration entity. It exports these properties: id, theme, region, weight, provider, plugin, settings and visibility. Placement therefore belongs to one theme and one region, and it is stored as configuration. Within a region, enabled blocks are sorted by weight and then by label. The block layout page is where you manage all of this.

You create your own text and media blocks with the Block Content module. Its entity type is called Content block, and each one has a Block description. The collection lives under Content › Blocks, at /admin/content/block, and the Add content block action starts a new one. A content block has no public page of its own; its canonical link is an admin edit page. Content blocks also have a Reusable flag, which defaults to on.

On the configure form, vertical tabs under Visibility set when a block shows. Pages takes one path per line and offers Show for the listed pages or Hide for the listed pages. Other tabs include Roles, Content type and, on multilingual sites only, Language.

Example

To add an opening-hours box to the footer, go to Content › Blocks and click Add content block. Write the text and save it. Then open Structure › Block layout, select the theme's tab and click Place block beside the Footer region. Choose your content block, then click Save block. Drag it to the right position and click Save blocks.

Common mistakes

  • Using the wrong theme tab. The Drupal User Guide notes that block placement is defined per theme. A block placed under another theme's tab does not appear in the theme your visitors see.
  • Using a region the theme does not declare. Drupal loads the blocks of the active theme and drops those whose region the theme does not declare.
  • Leaving out the leading slash. The Pages setting rejects a path such as about and asks for /about.

For marketing and content teams

Blocks hold the repeated parts of a site: promo boxes, footer text, newsletter forms. Edit a content block once under Content › Blocks and every placement shows the new text, because placements load the block by UUID. Content block administration uses the administer block content permission, and placing blocks needs administer blocks. For layouts that differ page by page, the core Layout Builder module lets users add and arrange blocks directly on the content.

With DXPR

DXPR Builder can place a Drupal block as an element inside a page. Write a section once as a content block, add that block to every page that needs it, and one edit updates them all. See DXPR Builder.

Sources

Questions about Block

A block is any placeable plugin, such as a menu, a search form or the breadcrumb trail. A content block is one kind of block: an entity of type block_content that you write yourself, with a Block description and fields. Placing it uses the block plugin block_content, which finds the entity by its UUID.

Open the block's configuration and use the Visibility tabs. Under Pages, enter one path per line, starting with a slash; the asterisk is a wildcard and <front> is the front page. You can also limit a block by role, by content type and, on multilingual sites, by language.

Check that it is enabled, that you placed it in the theme your visitors see, and that its region exists in that theme. Drupal only renders blocks of the active theme, and blocks whose region the theme does not declare are dropped from the page. Then review the visibility settings.

Yes. The Drupal User Guide says the same block can be placed several times, and each copy has its own configuration and visibility rules.

Cite this definition

"Block." DXPR Drupal glossary, https://dxpr.com/hc/documentation/learn-drupal/drupal-glossary/block. Last updated October 26, 2026.

Related terms

All Drupal terms from A to Z