Adding Regions to a Theme

Enabling a new region for a theme requires:

• Adding region metadata to your THEMENAME.info.yml file
• Printing the region as a Twig variable in your page.html.twig file (and page template variants)

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. You don't need to quote a YAML string, as long as the first character is not a special character. 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 is a human-readable version displayed in the admin UI.

Adding Regions to Your Templates

In order for regions to display any content placed in 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 machine-name 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

These are the default regions that appear when no regions key is set in the theme info file. They are defined in core/lib/Drupal/Core/Extension/ThemeExtensionList.php. They appear here in the order that they will appear in the block layout page.

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

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

These regions correspond with what the default core/modules/system/templates/page.html.twig file expects. Note that this template displays them in a different order. So, you may wish to define the regions key in your THEMENAME.info.yml file, if only to change to order.