Drupal theme folder structure

A theme is a collection of files that define the presentation layer. You can also create one or more "sub-themes" or variations on a theme. Only the .info.yml file is required, but most themes and sub-themes will use other files as well. This page lists the files and folders that are found in a typical theme or sub-theme.

Location of themes

You must place themes in the "themes" folder of your Drupal installation. Note that Drupal core themes such as Bartik and Seven are located in the core/themes folder of your installation.

It is good practice to place the contributed themes in a sub folder named "contrib" and your own themes in a folder named "custom".

Each individual theme is contained in a directory named after the theme itself. For example fluffiness/. The name must be all lowercase, start with a letter, and uses an underscore (_) instead of spaces.

The (partial) structure of your Drupal installation could look as follows:

  |-core
  |  |-modules
  |  |-themes
  |  |  |-bartik
  |  |  |-seven
  ..
  |-modules
  |-themes
  |  |-contrib
  |  |  |-zen
  |  |  |-basic
  |  |  |-bluemarine
  |  |-custom
  |  |  |-fluffiness

Theme folder structure

This is an example of the files and folders that are found in typical theme folder structure:

  |-fluffiness.breakpoints.yml
  |-fluffiness.info.yml
  |-fluffiness.libraries.yml
  |-fluffiness.theme
  |-config
  |  |-install
  |  |  |-fluffiness.settings.yml
  |  |-schema
  |  |  |-fluffiness.schema.yml
  |-css
  |  |-style.css
  |-js
  |  |-fluffiness.js
  |-images
  |  |-buttons.png
  |-logo.svg
  |-screenshot.png
  |-templates
  |  |-maintenance-page.html.twig
  |  |-node.html.twig

Below is a description of the most common files that you can find in a theme.

*.info.yml

A theme must contain an .info.yml file to define the theme. Among other things the .info.yml files define metadata, libraries, and block regions. This is the only required file in the theme.

*.libraries.yml

The .libraries.yml file is used to define JavaScript and CSS libraries that can be loaded by the theme.

*.breakpoints.yml

Breakpoints define where a responsive design needs to change in order to respond to different devices. Breakpoints are defined in a .breakpoints.yml file.

*.theme

The .theme file is a PHP file that contains all the conditional logic and data (pre)processing of the output. It may also extend basic theme settings. Creating advanced theme settings.

css/

It is good practice to store .css files in the 'css' subfolder. Drupal 8 core themes organize CSS files following the SMACSS style guide. For a theme to load CSS files they must be defined in .libraries.yml file and can be overridden or removed in .info.yml file.

js/

Theme specific JavaScript files are stored in the 'js' folder. For a theme to load JavaScript files they must be defined in .libraries.yml file.

images/

It is good practice to store images in the 'images' subfolder.

screenshot.png

If a screenshot.png file is found in the theme folder, then it will be used on the Appearance page. Alternatively, you can define a screenshot in .info.yml file.

logo.svg

If a SVG vector file of your theme's logo is found in the theme folder, then it may be used in the header of the website. Logos can also be uploaded at Appearance > Settings.

templates/

Templates provide HTML markup and some presentation logic. Contrary to Drupal 7, in Drupal 8 template files (*.html.twig files) must be stored in the 'templates' subfolder. If you follow particular naming conventions, then Drupal will replace the default core templates by the ones you provide, allowing you to override the default markup. You also can organize your templates in subfolders, for example all block templates inside templates/block and all views templates inside templates/views.

Core theme Bartik folder structure

For an example, look at the Bartik folder structure that is located at core/themes/bartik:

  |-bartik.breakpoints.yml
  |-bartik.info.yml
  |-bartik.libraries.yml
  |-bartik.theme
  |-color
  |  |-color.inc
  |  |-preview.css
  |  |-preview.html
  |  |-preview.js
  |-config
  |  |-schema
  |  |  |-bartik.schema.yml
  |-css
  |  |-colors.css
  |  |-layout.css
  |  |-maintenance-page.css
  |  |-print.css
  |-images
  |  |-add.png
  |  |-required.svg
  |  |-tabs-border.png
  |-logo.svg
  |-screenshot.png
  |-templates
  |  |-block--search-form-block.html.twig
  |  |-block--system-branding-block.html.twig
  |  |-block--system-menu-block.html.twig
  |  |-block.html.twig
  |  |-comment.html.twig
  |  |-field--taxonomy-term-reference.html.twig
  |  |-maintenance-page.html.twig
  |  |-node.html.twig
  |  |-page.html.twig
  |  |-status-messages.html.twig

More information

Coding standards: CSS file organization