Adding a region in theme

Adding regions to your theme requires:

• Adding region metadata in the THEMENAME.info.yml file.
• Editing the page.html.twig file and printing the new regions.

Note: If you declare any regions in your theme—even just one—the default regions will no longer apply, and you are responsible for declaring all the regions you intend to use.

Any blocks that were previously assigned to regions you have not redefined will be disabled. For example, if you edit THEMENAME.info.yml and rebuild the cache using drush cr, you’ll see messages like this for each affected block:

The block themename_breadcrumbs was assigned to the invalid region breadcrumb and has been disabled.

In /admin/structure/block, all disabled blocks will appear at the top with a (disabled) indicator. You can either drag them or use the “Region” dropdown to reassign them—or delete blocks you no longer need.

Be sure to keep the page_top and page_bottom regions. These are “hidden” areas used for markup at the top and bottom of the page, such as analytics scripts or the admin toolbar. You don’t need to list them in THEMENAME.info.yml—just don’t remove them from html.html.twig. Modules may rely on their presence.

Adding Regions to Your Info File

Begin by declaring new regions in your THEMENAME.info.yml file. Regions are declared as children of the regions key like this:

regions:
  header: 'Header'
  content: 'Content'
  footer: 'Footer'

Region keys must be alphanumeric and can include underscores (_). Keys must begin with a letter. The key is the machine name (used in code), and the value is the human-readable name shown in the admin interface.

Adding Regions to Your Templates

To display content placed in regions, ensure your new regions are also added to your page.html.twig file. Regions are represented as Twig variables whose names match the keys declared in THEMENAME.info.yml, prefixed with page.

Example:

header: 'Header'

...becomes:

{{ page.header }}

These behave like any other Twig variable and can be wrapped in whatever markup is suitable for your use case.

(Note: hidden region syntax is slightly different, see below.)

Default Regions

See the page.html.twig API documentation for a list of default regions.

• page.header
• page.primary_menu
• page.secondary_menu
• page.highlighted
• page.help (dynamic help text, mostly for admin pages)
• page.content (main content of the current page)
• page.sidebar_first
• page.sidebar_second
• page.footer
• page.breadcrumb

If your theme does not declare regions, Drupal will fall back to this default set.

These regions align with what is expected by the default template file core/modules/system/templates/page.html.twig, as well as two hidden areas: page_top and page_bottom. You do not need to declare these last two when overriding defaults, but the Twig variables {{ page_top }} and {{ page_bottom }} must be retained in your html.html.twig template.