Creating sub-themes

Sub-theming is a great solution, basing on and overriding a base theme. However, if you only need to add a little CSS or JavaScript, Asset Injector offers a quick and easy method.

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

Generating a new sub-theme using starterkit

A new sub-theme of Stable 9 can be generated in the /themes directory by running the following command:

php core/scripts/drupal generate-theme fluffiness

The generated theme is based on a core Starterkit theme, which includes some default templates and CSS that helps you get started with your subtheme of Stable 9.

Generating a new sub-theme using Drush

A new sub-theme can be generated by running the following Drush command:

drush generate theme

Answer the resulting command line questions and the skeleton of your new theme will be created for you. Enter the machine name of you desired base theme under question #3, "Base theme".

Note: Before installing your new sub-theme, you need to manually copy over the regions from the base-theme *.info.yml file into your new sub-theme, to allow inheriting block positions. See Inheriting Theme Regions and Inheriting Block Placement below.

Creating sub-theme manually: Fluffiness

Fluffiness is an example of a sub-theme that uses Stable 9 as a base theme.

This is the folder structure you'll end up with by implementing the following files.

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

The info file is named fluffiness.info.yml. You don't need to quote a YAML string, as long as the first character is not a special character.

name: Fluffiness
type: theme
description: This is a fluffy sub theme of Stable 9
core_version_requirement: ^8 || ^9 || ^10
# Defines the base theme
base theme: stable9
# Defines libraries group in which we can add CSS/JS.
libraries:
  - fluffiness/global-styling
# Regions, quote the names
regions:
  header: Header
  featured: Featured
  content: Content
  sidebar_first: First sidebar
  sidebar_second: Second sidebar
  footer: Footer

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

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

Read more about adding stylesheets (CSS) and JavaScript (JS) to a Drupal theme.

If you want to use a different name instead of fluffiness, just replace all occurrences of fluffiness with your own name (including the folder name), like the following, for example.

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

The text you put in the name: line of the info.yml file is free-form and doesn't need to exactly match your sub-theme's filename. For example, it could be like this.

name: My Custom Theme
# (all the other lines omitted for brevity)

Sub-theme of a sub-theme

When creating a sub-sub-theme of a sub-theme, you must specify the sub-theme you want to extend as a base theme.

• Fluffiness: First sub-theme of Stable 9
  

  name: Fluffiness
  type: theme
  description: This is a fluffy sub theme of Stable 9
  # Defines the base theme
  base theme: stable9
  

• Shaved: sub-theme of Fluffiness (sub-sub-theme of Stable 9)
  

  name: Shaved
  type: theme
  description: This is a reduced fluff sub theme of Fluffiness
  # Defines the base theme
  base theme: fluffiness
  

Note that the base theme:parameter is the machine name of the base theme, whereas the name: parameter is a descriptive name.

Inheriting Theme Regions

Theme regions are not inherited from the specified base theme.  If the regions: parameter is left blank in your sub-theme's info.yml file or doesn't contain all regions from your base theme, then Drupal default regions may be used as fallbacks for block placement in your sub-theme. We highly recommend copying all regions defined in your base theme into your sub-theme's info.yml file.

# Because regions are not inherited, any region including standard
# Drupal regions as well as base theme regions must be defined in
# the sub-theme. This example demonstrates a sub-theme that leverages
# a subset of the standard Drupal regions (1), plus some custom
# regions defined in the base theme (2), and finally three
# "fluffiness"-related sub-theme regions:
  # 1. Standard Drupal regions (also defined and used by base theme).
  # 2. Regions copied from base theme.
  # 3. Additional custom sub-theme regions.
  header:             Header                    # 1
  primary_menu:       Main menu                 # 1
  secondary_menu:     Secondary menu            # 1
  highlighted:        Highlighted               # 1
  help:               Help                      # 1
  section_nav:        Section Nav               # 2
  breadcrumb:         Breadcrumb                # 1
  page_title:         Page Title                # 2
  local_tasks:        Local Tasks               # 2
  content:            Content (Constrained)     # 1
  fluffiness_fullwidth: Content (Edge-to-edge)  # 2
  fluffiness_first:     Fluffiness First        # 3
  fluffiness_second:    Fluffiness Second       # 3
  fluffiness_third:     Fluffiness Third        # 3
  footer:             Footer                    # 1

Inheriting Block Placement

In Drupal, themes may come with config/install/ or config/optional/ folders where pre-defined block configurations—including placement into theme regions—will be imported upon enabling the theme. If a sub-theme does not supply its own block configurations, Drupal will inherit these block configurations and region placement from the base theme. But, if the theme regions defined in your sub-theme's info.yml file do not match those available in the base theme, unpredictable placements in random regions can occur. 

Block placement inheritance only occurs:

• From the current default theme
• Only if the sub-theme does not have any of its own block placement configs
• Will place blocks in the theme's default region if a matching region could not be found

Since admin themes (such as Claro) are typically not the default theme, a workaround to inheriting block placement is to copy over the claro/config/optional folder and edit file names and variables inside the files to match you sub-theme. See #3372705, #2635166 and #3278410 for more.

Inheriting Block Templates

If the theme you are extending has custom block templates these won't be immediately inherited because a sub-theme creates copies of all the blocks in the parent theme and renames them with the sub-theme's name as a prefix. Twig block templates are derived from the block's name, so this breaks the link between these templates and their block. Fixing this problem currently requires a hook in the sub-theme. Following the examples above, we'd create a file called shaved.theme in the sub-theme's directory. In that file insert this code.

/**
 * Implements hook_theme_suggestions_HOOK_alter for blocks.
 */
function shaved_theme_suggestions_block_alter(&$suggestions, $variables) {

  // Load theme suggestions for blocks from parent theme.
  foreach ($suggestions as &$suggestion) {
    $suggestion = str_replace('shaved_', 'fluffiness_', $suggestion);
  }
}

For your own sub-themes replace shaved with the name of your sub-theme and fluffiness with the name of your base theme. 

Inheriting Configuration Schema

Just like regions and block placement, configuration schema also needs to be explicitly extended for sub-themes.  

Configuration schema tells Drupal how to handle your theme’s settings during configuration export/import.

If your sub-theme inherits settings from a base theme, locate the base theme’s schema file (for example, stable9/config/schema/stable9.schema.yml) and extend its schema type in your subtheme’s schema file.  

For example, the base theme might define:

stable9.settings:
  type: theme_settings
  label: 'Stable 9 settings'
  mapping:
    whisker_length:
      type: integer
      label: 'Whisker length'

Your sub-theme Fluffiness should extend that schema, while adding its own setting:

fluffiness.settings:
  type: stable9.settings
  label: 'Fluffiness settings'
  mapping:
    fluffiness_level:
      type: integer
      label: 'Fluffiness level'

This ensures your sub-theme inherits all configuration definitions from the base theme (like whisker_length) while letting you add custom ones (like fluffiness_level).

Note: If you are creating a sub-sub-theme, it should extend its immediate parent’s settings type.

For example, a sub-theme named Shaved that extends Fluffiness would define:

shaved.settings:
  type: fluffiness.settings
  label: 'Shaved settings'
  mapping:
    fluffiness_reduction:
      type: integer
      label: 'Fluffiness reduction level'

Avoid "No available releases found"

If you see your sub-theme listed with a "No available releases found" warning on the "Available updates" page at /admin/reports/updates page, it may be due to a project: 'My theme' entry in the *.info.yml file. Just remove the line, and the warning should disappear. See also #208201: ignore certain projects at update scan.

Differences with Drupal 7

The most notable difference with Drupal 7 is that .info files have become YAML files that use .info.yml as an extension.