Subthemes

Sub-themes, like any other theme, differ in one key way: they inherit resources from their parent theme. There are no limitations to the chaining capabilities connecting sub-themes to their parents. A sub-theme can be a child of another sub-theme, and it can be branched and organized however you see fit. This is what gives sub-themes great potential.

To create a sub-theme, define it like any other theme and declare its base theme using the "base theme" key. (Note that this key has no underscore.)

Sub-theme example: Fluffiness

Fluffiness is an example sub-theme that uses Classy as a base theme.

This is the folder structure you’ll have with the following files:

themes/
└──  fluffiness/
     ├── fluffiness.info.yml
     └── fluffiness.libraries.yml

The info file is named fluffiness.info.yml:

name: Fluffiness
type: theme
description: This is a fluffy sub theme of Classy
core: 8.x
base theme: classy
libraries:
  - fluffiness/global-styling
regions:
  header: Header
  featured: Featured
  content: Content
  sidebar_first: First sidebar
  sidebar_second: Second sidebar
  footer: Footer

Include a fluffiness.libraries.yml file to add CSS/JS to the global styling group defined above:

global-styling:
  css:
    component:
      css/style.css: {}

Learn more about adding CSS and JS to a Drupal 8 theme.

If you want to use another name instead of "fluffiness", simply replace all occurrences of "fluffiness" with your theme name (including the folder name). For example:

themes/
└──  my_custom_theme/
     ├── my_custom_theme.info.yml
     └── my_custom_theme.libraries.yml

The text you enter in the "name:" line of the info.yml file is arbitrary and does not have to exactly match the file name of your sub-theme. For example:

name: My Custom Theme

Sub-theme of a sub-theme

When creating a sub-theme of a sub-theme, you must set the sub-theme as the base theme.

• Fluffiness: first sub-theme of Classy

name: Fluffiness
type: theme
description: This is a fluffy sub theme of Classy
core: 8.x
base theme: classy

• Shaved: sub-theme of Fluffiness (sub-theme of Classy)

name: Shaved
type: theme
description: This is a reduced fluff sub theme of Fluffiness
core: 8.x
base theme: fluffiness

Note that base theme: is the machine name of the base theme, while name: is the human-readable label.

Region inheritance

Theme regions are not inherited from the base theme. If the regions: key is left blank or does not include all regions from the base theme, then default Drupal regions may be used as fallbacks. It is strongly recommended to copy all regions defined in your base theme into the info.yml file of your sub-theme.

regions:
  header:             'Header'
  primary_menu:       'Main menu'
  secondary_menu:     'Secondary menu'
  highlighted:        'Highlighted'
  help:               'Help'
  section_nav:        'Section Nav'
  breadcrumb:         'Breadcrumb'
  page_title:         'Page Title'
  local_tasks:        'Local Tasks'
  content:            'Content (Constrained)'
  content_fullwidth:  'Content (Edge-to-edge)'
  colophon_first:     'Colophon First Col'
  colophon_second:    'Colophon Second Col'
  colophon_third:     'Colophon Third Col'
  footer:             'Footer'

Block placement inheritance

In Drupal 8, themes can include a config/install/ folder with pre-defined block configurations, including region placements, which are imported when the theme is enabled. Drupal can inherit these block placements from the base theme, but if the region names in your sub-theme's info.yml do not match those in the base theme, blocks may be unpredictably placed.

Block template inheritance

If the base theme has custom block templates, they are not automatically inherited. A sub-theme creates copies of all blocks and renames them with its theme name as a prefix, which breaks the connection to the parent’s Twig templates. To fix this, use a hook in your sub-theme. Create a shaved.theme file in your sub-theme directory with the following code:

/**
 * Implements hook_theme_suggestions_HOOK_alter for blocks.
 */
function shaved_theme_suggestions_block_alter(&$suggestions, $variables) {
  foreach ($suggestions as &$suggestion) {
    $suggestion = str_replace('shaved_', 'fluffiness_', $suggestion);
  }
}

For your own sub-themes, replace “shaved” with your sub-theme’s machine name, and “fluffiness” with your base theme’s machine name.

Differences from Drupal 7

The most noticeable difference from Drupal 7 is that .info files are now .info.yml files, using YAML syntax.