Theme folder structure in Drupal

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

Theme Location

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

It is recommended to place contributed themes in a "contrib" subfolder, and your own custom themes in a "custom" folder.

Each theme is contained in a directory named after the theme itself—for example, "fluffiness". The name must be lowercase, start with a letter, and use underscores (_) instead of spaces.

Your Drupal installation directory structure might look like this:

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

Theme Folder Structure

This is an example of files and folders found in a typical theme directory:

  |-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 you might find in a theme.

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

*.libraries.yml
The .libraries.yml file defines JavaScript and CSS libraries that can be loaded by the theme.

*.breakpoints.yml
Breakpoints define when responsive design should change to accommodate different devices. They are defined in a .breakpoints.yml file.

*.theme
The .theme file is a PHP file containing all conditional logic and data preprocessing. It can also extend core theme settings. Creating advanced theme settings.

CSS/
It is recommended to store .css files in a 'css' subfolder. Core Drupal 8 themes organize CSS files according to the SMACSS style guide. To load CSS files in your theme, they must be defined in the .libraries.yml file and can be overridden or removed in the .info.yml file.

JS/
JavaScript files specific to the theme are stored in the 'js' folder. To load JavaScript files in your theme, they must be defined in the .libraries.yml file.

images/
It is recommended to store images in an "images" subfolder.

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

logo.svg
If an SVG logo file is in the theme folder, it can be used in the site header. Logos can also be uploaded under Appearance > Settings.

templates/
Templates provide HTML markup and some presentation logic. Unlike Drupal 7, Drupal 8 template files (*.html.twig) must be stored in the 'templates' subfolder. If you follow specific naming conventions, Drupal will replace core default templates with those you provide, allowing you to override the default markup. You can also organize templates into subfolders, e.g., all block templates in templates/blocks and all view templates in templates/views.

Bartik Core Theme: Folder Structure

For example, take a look at the Bartik folder structure 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: organizing CSS files