Defining a theme with an .info.yml file

To create a theme for Drupal 8 or later, you need to first create a THEMENAME.info.yml file that provides meta-data about your theme to Drupal. This is similar to how modules and installation profiles are being defined, and as such, it is important to set the 'type' key in the file.info.yml to 'theme' in order to differentiate it.

This page provides an example fileTHEMENAME.info.yml and an overview of the information that the file can contain.

Name your theme

The first step in creating a theme is to choose a human-readable name for it, and a corresponding machine name. The machine name will be used as the name for files, folders, and functions in your theme, and is used by core Drupal programmatically to refer to your theme. The machine name is usually the human-readable name, converted to lower-case and with underscores instead of spaces. For example, if your theme is named "Fluffiness", then the machine name is "fluffiness". If your theme name is longer, like "Very Fluffy", your machine name would be "very_fluffy".

There are some important rules to follow when selecting a machine name:

• It must start with a letter.
• It must contain only lower-case letters, numbers and underscores.
• It must not contain any spaces.
• It must not be longer than 50 characters.
• It must be unique. Your theme should not have the same short name as any other module, theme, theme engine, or installation profile you will be using on the site.
• It should not be any of the reserved terms (folders in the Drupal distribution): src, lib, vendor, assets, css, files, images, js, misc, templates, includes, fixtures, drupal.

Create an .info.yml file

Create the .info.yml file in the root of your themes folder. The folder name is the machine name, and the info file name is machine_name.info.yml. For the rest of this page, we'll create a theme whose human-readable name is "Fluffiness" and machine name is "fluffiness", so the folder is named "fluffiness/" and the .info.yml file is named "fluffiness/fluffiness.info.yml". If the file is present with the minimum required properties (name, type, base theme and core/core_version_requirement) your theme will be visible on your website at Manage > Appearance (http://example.com/admin/appearance).

If you are not familiar with the YAML file structure, read the quick introduction to the YAML file format.

• Tabs are NOT allowed. Use spaces ONLY.
• Properties and lists MUST be indented by two (2) spaces.

Example

name: Fluffiness
type: theme
description: 'A cuddly theme that offers extra fluffiness.'
core_version_requirement: '>=9.2'
libraries:
  - fluffiness/global-styling
base theme: stable9
regions:
  header: 'Header'
  content: 'Content'
  sidebar_first: 'Sidebar first'
  footer: 'Footer'

In your Drupal website, you can find more examples of .info.yml files by looking at the themes provided by core. For example, open the folder andcore/themes/stark look for the file stark.info.yml.

Key/value pairs

The following key/value pairs provide meta-data about your theme and define some of the basic functionality. (See \Drupal\Core\Extension\InfoParserInterface::parse().)

• name (required)
• type (required)
• base theme (required in Drupal 9 and later, optional for Drupal 8)
• core_version_requirement (required in Drupal 9 and later, optional for Drupal 8)
• core (required for Drupal 8, optional if you include core_version_requirement , not valid for Drupal 9 and later)
• description (optional)
• dependencies (optional)
• package (optional)
• php (optional)
• version (optional)
• libraries (optional)
• libraries-override (optional)
• libraries-extend (optional)
• hidden (optional)
• engine (optional)
• logo (optional)
• screenshot (optional)
• regions (optional)
• regions_hidden (optional)
• features (optional)
• stylesheets-remove (deprecated)
• ckeditor_stylesheets (optional)
• ckeditor5-stylesheets (optional)

name (required)

The human-readable name. This will appear on the "Appearance" page where the theme is activated.

name: Fluffiness

type (required)

Indicates the type of extension, i.e., "module", "theme", or "profile". For themes this should always be set to "theme". This value is case-sensitive.

type: theme

base theme (required)

A theme can inherit the resources from another theme by specifying it as a base theme. It is recommended to use stable9. If set to false, no base theme is being used. (note, if you are changing the base theme of an already-enabled theme, and the base theme is not enabled, uninstall then reinstall the theme so it registers and enables the new base theme)

base theme: stable9

core_version_requirement (required)

Allows modules, themes, and profiles to specify that they are compatible with multiple major versions of Drupal core.

core_version_requirement: ^9 || ^10

Using '>=9.2' marks it as compatible with all versions of core from 9.2 and onward:

core_version_requirement: '>=9.2'

description (optional)

The description, displayed on the "Appearance" page.

description: An extra cuddly Drupal theme available in grey and blue.

dependencies (optional)

List of machine names of other themes necessary to be present and installed to get this theme installed. The base theme is not necessary to get listed here in extra.

Introduced in 8.9.x

See change record.

List of machine names of modules necessary to be present and installed to get this theme installed.

dependencies:
  - my_custom_module:my_custom_module
  - drupal:views
  - paragraphs:paragraphs
  - components:components (>=8.x-2.x)

package (optional)

Specifies a "package" that allows you to group themes together.

package: Core

core (required for Drupal 8)

Specifies the version of Drupal core that the theme is compatible with.

core: 8.x

It can be omitted if you specify core_version_requirement and don't support Drupal 8.7.7 and below. See change record.

php (optional)

The minimum version of PHP required. Defaults to the value of DRUPAL_MINIMUM_PHP constant.

php: 5.5.9

version (optional)

Specifies a version. For themes hosted on drupal.org, the version number will be filled in by the packaging script. Do not specify it manually, but leave out the version line entirely.

version: 8.x-1.0

or

version: '1.0'

libraries (optional)

A list of libraries (which can contain both CSS and JavaScript assets) to add to all pages where the theme is active. Read more about themes and asset libraries.

libraries:
  - fluffiness/global-styling

libraries-override (optional)

A collection of libraries and assets to override. Read more at Overriding and extending libraries.

libraries-override:
  contextual/drupal.contextual-links:
    css:
      component:
        /core/themes/stable/css/contextual/contextual.module.css: false

libraries-extend (optional)

A collection of libraries and assets to add whenever a library is attached. Read more at Overriding and extending libraries.

libraries-extend:
  core/drupal.user: 
    - fluffiness/user1
    - fluffiness/user2

hidden (optional)

Indicates whether or not to hide the theme from the "Appearance" page so that it cannot be enabled/disabled via the UI.

hidden: true

engine (optional)

The theme engine. Defaults to "twig".

engine: twig

logo (optional)

Introduced in 8.6.x

See change record.

The path to logo relative to the theme's .info.yml file. By default, Drupal will look for a file named "logo.svg" in the root of your theme folder and use that as the theme's logo.

logo: images/logo.png

screenshot (optional)

The path to screenshot relative to the theme's .info.yml file. Screenshots should be 588 pixels wide and 438 pixels high, though they are displayed at a smaller size. By default, Drupal will look for a file named "screenshot.png" in the root of your theme folder and use that as the theme image on the "Appearance" page.

screenshot: fluffiness.png

regions (optional)

A list of theme regions. (Note that region keys are not preceded by a dash.) A content region is required. Read more about adding regions to a theme.

regions:
  header: Header
  content: Content
  sidebar_first: 'First sidebar'

regions_hidden (optional)

A list of inherited regions to remove.

regions_hidden:
  - sidebar_last

features (optional)

A list of features to expose on the theme "Settings" page.

features:
  - comment_user_verification
  - comment_user_picture
  - favicon
  - logo
  - node_user_picture

stylesheets-remove (deprecated)

A list of stylesheets from other modules or themes to remove from all pages where the theme is active. Each value must be a full path relative to the docroot to resolve ambiguity when more than one file with the same name exists. In cases where the file is part of a library that belongs to a module or theme, a token in the form @module_or_theme_name can be used in place of the full path. Note that when using the token the value must be quoted because "@" is a reserved indicator in YAML. Note: This key is deprecated and will be removed in Drupal 9. In most cases libraries-override should be used.

stylesheets-remove:
  - core/assets/vendor/normalize-css/normalize.css
  - '@stable9/css/core/assets/vendor/normalize-css/normalize.css'

ckeditor_stylesheets (optional)

A list of stylesheets to add to the CKEditor frame.

ckeditor_stylesheets:
  - https://fonts.googleapis.com/css?family=Open+Sans
  - css/base/elements.css

ckeditor5-stylesheets (optional)

A list of stylesheets to add to the CKEditor5 frame.

ckeditor5-stylesheets:
  - https://fonts.googleapis.com/css?family=Ubuntu
  - css/base/elements-ckeditor5.css

Introduced in 9.3.x

See change record.

More information

• Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme
• A full description of all the keys that are available in a *.info.yml file can be found in: Let Drupal 8 know about your module with a .info.yml file
• Change record: .info files are now .info.yml files