Defining a theme with an .info.yml file

Last updated on
22 June 2017

To create a Drupal 8 theme 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 .info.yml file to 'theme' in order to differentiate it.

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

Create an .info.yml file

Create the .info.yml file in the root of your theme folder. The folder should have the same name as the .info.yml file. So if your theme is named "Fluffiness" then the folder is named "fluffiness/" and the .info.yml file is named "fluffiness/fluffiness.info.yml". If the file is present your theme will be visible in your website at Manage > Appearance (http://example.com/admin/appearance). Remember to choose a theme name which is not already being used by a module or a different theme. The theme name must be a unique name in the Drupal setup. Otherwise the theme components will not be properly loaded.

Replace spaces in the theme name with underscores in the folder name (and .info.yml file name).

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: 8.x
libraries:
  - fluffiness/global-styling
base theme: classy
regions:
  header: Header
  content: Content
  sidebar_first: 'Sidebar first'
  footer: Footer
stylesheets-remove:
  - '@classy/css/components/tabs.css'
  - core/assets/vendor/normalize-css/normalize.css

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 core/themes/stark and 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)
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".
type: theme
description (optional)
The description, displayed on the "Appearance" page.
description: An extra cuddly Drupal theme available in grey and blue.
package (optional)
Specifies a "package" that allows you to group themes together.
package: Core
core (required)
Specifies the version of Drupal core that the theme is compatible with.
core: 8.x
php (optional)
The minimum version of PHP required. Defaults to 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
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
base theme (recommended)
A theme can inherit the resources from another theme by specifying it as a base theme. It is recommended to use classy or stable (stable is the default if the key is not supplied) – this makes it easier for your theme to inherit future changes in core theming.
base theme: classy
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
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
  - '@classy/css/components/tabs.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

More information