Region

A region is a named area of a Drupal theme's page, such as Header, Content or Footer. The theme declares its regions under the regions key of its .info.yml file and prints each one in a template as page.machine_name. A block is placed into exactly one region, and the theme decides where that region appears.

How regions work in Drupal 11

A region has a machine name and a label. In Twig the machine name becomes a variable on the page: a region named header is printed as {{ page.header }} in page.html.twig. The core template prints some regions always and wraps others, such as the sidebars and the footer, in a condition, so an empty one leaves no markup.

A theme that declares no regions gets twelve defaults from ThemeExtensionList: sidebar_first, sidebar_second, content, header, primary_menu, secondary_menu, footer, highlighted, help, page_top, page_bottom and breadcrumb. Declare even one region and these defaults no longer apply. The Drupal User Guide says only the Content region is required.

The regions_hidden key hides regions from the block interface, and the System module adds page_top and page_bottom to it for every theme. The Block layout page lists only visible regions.

Example

Olivero declares thirteen regions, among them Header, Primary menu, Hero (full width), Breadcrumb, Content Above, Content, Sidebar, Content Below, Footer Top and Footer Bottom. A small custom theme might declare these:

regions:
          header: Header
          content: Content
          footer: Footer
          page_top: Page top
          page_bottom: Page bottom

Its page.html.twig then needs {{ page.header }}, {{ page.content }} and {{ page.footer }} where each area should appear.

Common mistakes

• Declaring one region and losing the rest. Blocks that sat in the vanished regions are not rendered, and a cache rebuild disables them.
• Dropping page_top and page_bottom. The Drupal.org guide says to keep them and not to remove them from html.html.twig. The System module reserves them for modules to fill.
• Declaring a region but not printing it. The template must output page.machine_name or the blocks placed there do not appear on the page.

For marketing and content teams

Regions are the slots your design offers, and you cannot add one from the admin screens, because they are declared in the theme's code. Moving a block between existing regions is a task for Structure › Block layout; the block layout page also orders blocks inside a region by weight. If a campaign needs a new slot, such as a banner above the header, ask your developer to add a region to the theme.

With DXPR

DXPR Theme declares its own regions, for example Hero Region, Content Top and Content Bottom, so its Block layout page differs from Olivero's. DXPR Builder can also place a Drupal block as an element inside the page body, so a block does not always need a theme region. See DXPR Builder and DXPR Theme.

Sources

• Drupal.org: Adding regions to a theme
• Drupal.org: Defining a theme with an .info.yml file
• Drupal User Guide: Concept: Regions
• Drupal User Guide: Concept: Blocks
• ThemeExtensionList, Drupal 11.4.0 source
• Theme extension class, Drupal 11.4.0 source
• SystemHooks, Drupal 11.4.0 source
• BlockRepository, Drupal 11.4.0 source
• BlockHooks, Drupal 11.4.0 source
• Olivero theme info file, Drupal 11.4.0 source
• page.html.twig, Drupal 11.4.0 source