Adding Regions to a Theme

Last updated on
20 January 2024

This documentation needs review. See "Help improve this page" in the sidebar.

Adding regions to a theme requires:

  • Adding region meta-data to your THEMENAME.info.yml file.
  • Editing your page.html.twig file and printing the new regions.

Note: If you declare any regions in your theme, even just one, all the default regions will no longer be applied and you assume responsibility for declaring any and all regions you want to use.  

Any blocks that were in regions which no longer exist (because you didn't define them) will now be disabled - specifically if you edit THEMENAME.info.yml and rebuild the cache with drush cr, you'll see a message like this for each:

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

If you visit /admin/structure/block, any disabled blocks are listed in the topmost region, with a "(disabled)" indicator. You can either drag and drop or use the Region drop-down to reassign them or remove the blocks you no longer need.

Make sure you keep the page_top and page_bottom regions.  These are 'hidden' regions, used for markups at the very top and bottom of the page, such as analytics or the admin toolbar.  You don't need to list them in your THEMENAME.info.yml file, just don't remove them from the html.html.twig template.  Modules may rely on them being present.

Adding Regions to Your Info File

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

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

Region keys should be alphanumeric and can include underscores (_). Keys should begin with a letter. The key is the machine name (which you use in code) and the value a human readable version displayed in the admin UI.

Adding Regions to Your Templates

In order for regions to display any content placed into them, you'll need to make sure your new regions are also added to your page.html.twig file. Regions will be represented as Twig variables whose name corresponds with the key used in your THEMENAME.info.yml file with the string page. prepended.

Example:

header: 'Header' 

...will become:

{{ page.header }} 

These behave like any other Twig variable and may be wrapped in whatever markup makes sense for your use case.

(The syntax for the default hidden regions is different, see below.)

Default Regions

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

regions:
  header: 'Header'
  primary_menu: 'Primary menu'
  secondary_menu: 'Secondary menu'
  highlighted: 'Highlighted'
  help: 'Help'
  content: 'Content'
  sidebar_first: 'Left sidebar'
  sidebar_second: 'Right sidebar'
  footer: 'Footer'
  breadcrumb: 'Breadcrumb'
  page_top: 'Page top'
  page_bottom: 'Page bottom'

The default regions are defined in core/lib/Drupal/Core/Extension/ThemeExtensionList.php

If your theme doesn't declare any regions, Drupal will assume this set of defaults.

These regions correspond with what the default core/modules/system/templates/page.html.twig file expects, as well as two hidden regions, page_top, and page_bottom - you don't need to declare these final two if you override the defaults, however the {{ page_top }} and {{ page_bottom }} Twig variables should be retained in the html.html.twig template.

Help improve this page

Page status: Needs review

You can: