Block layout

The screen that decides which blocks appear in each region of a Drupal theme and in what order; every change is saved as configuration.

Learn DrupalDrupal glossary
Edited by Founder and CEO, DXPR Last updated

Block layout is the Drupal admin page, at Structure › Block layout, where you place blocks into a theme's regions, drag them into order, disable them or remove them. It has one tab per theme, because block placement is stored per theme. The page requires the administer blocks permission.

How the block layout page works in Drupal 11

The route block.admin_display lives at /admin/structure/block and has the title Block layout. Each theme that has a UI gets a tab, created by the ThemeLocalTask deriver; the default theme's tab comes first. Other tabs point to /admin/structure/block/list/{theme}.

Under each visible region heading, the table lists its blocks in columns named Block, Category, Region, Weight and Operations. An empty region shows the text No blocks in this region. The Place block button next to a region opens the block library in a modal dialog. Operations include Configure and Remove, plus Disable or Enable.

Rows can be dragged to change order and region. The Drupal User Guide adds that Show row weights swaps the handles for numeric weights, where lower values appear first.

The page changes configuration. Each placement is a block configuration entity, so it follows your normal configuration workflow. When a theme that brings no placements of its own is installed, Drupal copies the default theme's placements to it.

Example

To put a newsletter box in the sidebar, go to Structure › Block layout and open the tab of the theme your visitors see. Click Place block beside the sidebar region, then choose the block from the library. In the configuration dialog, check the region, optionally limit the pages, and click Save block. Drag it to the right spot and click Save blocks.

Placing a block in a region on the Block layout pageOn Structure, Block layout, open the tab of the theme, click Place block beside a region such as Sidebar, click Place block next to the block in the library, then set its title, visibility and region in the Configure block dialog and click Save block. To change the order, drag the row and click Save blocks. The block then renders in that region of the theme's pages, where its visibility settings allow.1. Structure › Block layout/admin/structure/block; needs administer blocks2. Open the tab of the themeThe default theme's tab is first, for example Olivero3. Click Place block beside a regionFor example Sidebar; the block library opens4. Click Place block next to the blockFilter by block name to find it5. Configure block, then Save blockRegion is preselected; set Title and Visibility6. Optional: drag it into orderThen click Save blocksOn the siteThe block renders inthat region of thetheme's pages, wherevisibility allowssavedEach placement is saved as a block configuration entity of that theme.
Placing a block: open the theme's tab, click Place block beside a region, pick the block, configure it and click Save block.

Common mistakes

  • Working in the wrong theme's tab. The Drupal User Guide stresses that block placement is defined per theme. Check the tab before you edit.
  • Forgetting Save blocks. Dragging only changes the form. Leave the page without saving and the old order stays.
  • Looking for hidden regions. The page lists only visible regions, so page_top and page_bottom never appear.
  • Expecting page-by-page layouts. This page arranges blocks per theme. For a layout that differs between pages, use a tool built for that, such as Layout Builder or DXPR Builder.

For marketing and content teams

Requests such as "move the banner" or "hide the signup box on the pricing page" are handled here. Ask for the administer blocks permission, or ask a site builder to do it. Each change applies to every page that prints that region in that theme, within the block's visibility rules, so test visibility rules on a staging copy first. The theme decides which regions exist.

With DXPR

Some blocks do not need a region. DXPR Builder can place a Drupal block as an element inside a page, so a block can sit in the page body, next to the text it supports. See DXPR Builder.

Sources

Questions about Block layout

Open Manage › Structure › Block layout, at /admin/structure/block. You need the administer blocks permission. The page opens on the default theme's tab; the other installed themes have their own tabs.

The page is one form. Dragging a row only changes the form until you click Save blocks at the bottom. Click it after every round of moving blocks between regions or changing weights.

The block layout puts blocks into the regions of a theme, so the same arrangement applies wherever the theme prints that region. Layout Builder is a separate core module that, according to its description, lets users add and arrange blocks and content fields directly on the content.

A disabled block stays in the list with the suffix (disabled), keeps its settings, and Drupal denies it view access, so it does not render. Remove asks you to confirm and then deletes the placement. To show the block again, you place it again.

Related terms

All Drupal terms from A to Z