Theme

A Drupal theme is an installable extension that renders the markup and styling of pages; one theme serves visitors and another can serve the admin pages.

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

A theme is the part of a Drupal site that controls how it looks. It is a folder with a machine_name.info.yml file, Twig templates, CSS and JavaScript libraries and, if needed, PHP code. The info file also declares the regions where blocks can be placed on a page.

How themes work in Drupal 11

The info file is the only required piece. The Drupal.org guide lists name, type (always theme), base theme and core_version_requirement as the minimum. Optional keys include libraries, which attach CSS and JavaScript, and regions. Markup comes from Twig templates. Olivero, for example, ships a breadcrumb.html.twig headed "Theme override for a breadcrumb trail" next to the default one in the System module.

A site has one default theme for visitors and, optionally, a separate administration theme. Both are stored in the system.theme configuration, in the default and admin keys. In the released Drupal 11.4 line, 11.4.10 and 11.4.11 when checked on 26 October 2026, the Standard installation profile sets Olivero as default and Claro as administration theme. In 11.5.0-beta1, a beta released on 15 October 2026, it sets Default Admin for both keys, and Olivero and Claro are marked deprecated. Themes can also stack: a sub-theme names a parent in base theme and inherits its templates and function implementations.

Block placement belongs to a theme. When a theme that brings no block placements of its own is installed, Drupal copies the default theme's blocks to it, and moves any block whose region the new theme lacks into its default region.

Example

To start a custom theme, generate it from the Starterkit theme instead of copying a core theme. From Drupal 11.4 the command is:

vendor/bin/dr generate-theme my_new_theme

The command writes the new theme to the themes directory. Go to Manage › Appearance, find it under Uninstalled themes and click Install and set as default.

Common mistakes

  • Editing a core theme. The Olivero info file warns that its markup and assets will change between minor releases. It advises copying the whole theme under a new name, or sub-theming it for minor tweaks only.
  • Choosing Stable 9 as a base for new work. Its info file hides it, and from Drupal 11.4 it also marks its lifecycle as deprecated.
  • Forgetting that blocks are per theme. After you switch themes, review the block layout of the new theme.

For marketing and content teams

The default theme sets the look of every public page at once, so changing it is a site-wide decision. Content stays in place, but header, footer and sidebar blocks can land in different regions or in none. Ask your developer to rehearse a theme change on a copy of the site before it goes live.

With DXPR

DXPR Theme is a Drupal theme with its own theme settings under Appearance and its own regions, such as Hero Region, Content Top and Content Bottom. See DXPR Theme.

Sources

Questions about Theme

Download the theme with Composer, open Manage › Appearance, find it under Uninstalled themes and click Install and set as default. The Drupal User Guide says all non-administrative pages then use the new theme. Check Structure › Block layout afterwards, because blocks are placed per theme.

Yes. The Appearance page has an Administration theme setting. Its first option is Default theme, which makes admin pages use the same theme as the rest of the site. The choice is saved in the admin key of the system.theme configuration; an empty value means Default theme.

Generate it from the Starterkit theme. From Drupal 11.4 run vendor/bin/dr generate-theme my_new_theme in the Drupal root; up to 11.3 the command is php core/scripts/drupal generate-theme my_new_theme. The theme is written to the themes/ directory unless you pass --path.

A base theme is a parent that another theme builds on. Drupal lets a sub-theme inherit templates and function implementations from its base theme. The info file names the parent with the base theme key, and false means the theme has none.

Related terms

All Drupal terms from A to Z