Building a Theme in Drupal 8

After a huge effort by the community over the past few years Drupal 8 is nearly here, and some of the most significant improvements are in the front end.

I recently took D8 for a spin and tested out creating a basic theme to see what's changed and how it's done.

NB. whilst the information in this post is still correct, you may also like to see our more recent post on Drupal 8 theming.

What’s Changed Since Drupal 7?

The front-end layer in Drupal 8 has been brought up to date with what you'd expect from a modern web framework. It still all feels "Drupally" and is still easy enough to pick up and get going with, but instead of re-inventing the wheel everywhere, tried and tested third-party libraries are included and well thought-out standards are adhered to. There is also better support for responsive design, front-end performance optimisation and the whole theme layer is more extensible and (I think) it's nicer for developers to work with.

Some of the headline improvements to the front end include:

  • Twig replaces PHPTemplate
  • The entire theme layer has been overhauled and simplified
  • Underscore.js & Backbone.js, Modernizr, jQuery UI Touch Punch, domready, are available as libraries (although by default no Javascript is loaded)
  • WAI-ARIA attributes, and HTML5 elements are used throughout core
  • ClassList & HTML5shiv Polyfill's are included, but loaded conditionally via Modernizr
  • Responsive breakpoints can be defined by themes for use within modules such as the Picture module (which is now in core)

For a more comprehensive look at the theme system in Drupal 8 check out the following articles:

I also suggest taking a look at what's changed in Drupal 8 generally, as a LOT has!

Creating a Theme in Drupal 8

To build a simple theme, I started by creating a new directory and a [themename].info.yml file, I called my theme ‘basis’.

I’ve started by just defining the basic meta-data for the theme and two stylesheets.

screenshot of the info.yml file

That’s it! Enabling the theme gives us a fairly minimal starting point to build from.

Take a look at the Writer, Prius and core Drupal themes to see some examples of how Drupal 8 themes are constructed.

Theme Settings

The [themename].info.yml file is where all the main theme settings and components are declared. Common settings for a Drupal 8 theme are:

  • Theme info or meta-data (name, description, version etc)
  • Stylesheets (including overrides)
  • Libraries
  • Regions
  • Settings
  • Features

By default the Drupal 8 theme regions  provided are:

  • Left sidebar
  • Right sidebar
  • Content
  • Header
  • Primary menu
  • Secondary menu
  • Footer
  • Highlighted
  • Help
  • Page top
  • Page bottom

To modify these regions we’ll need to declare all regions available to the theme in our .info.yml file. The page_top and page_bottom regions are special regions reserved for Drupal to add additional markup, they will not appear on the block layout page, they don’t have to be declared but it makes sense to declare all regions here, visible or not.

We can also use the new stylesheets-override and stylesheets-remove theme .info.yml file properties. Overriding a CSS file uses only the filename, so you can declare a stylesheets-override and place your CSS file within a theme subdirectory.

Screenshot of .info.yml file

CSS & Javascript

Adding single CSS and Javascript files to a theme is straightforward, using the 'scripts' or 'stylesheets' settings. There are also some more advanced capabilities, with modules and themes able to declare and use 'libraries'. These are groups of Javascript and CSS and dependencies of the library, once a Library has been declared Drupal will load it in only the place it has been declared in. In the case of declaring a Libarary within a theme, the library and dependencies will be loaded on every page using that theme. See Adding JavaScript to a Drupal 8 theme for more info.

There also seems to be the ability for modules allow overrides to be declared in *.info.yml files. I've seen this in the quickedit and ckeditor module, see for an example.

Also see Aten Desin Group's blog post Looking at Drupal 8's JavaScript Changes for a more detailed look at Javascript changes in Drupal 8.


The new templating system in Drupal is the fantastic Twig, which enforces better separation of logic and presentation and should be more intuitive to use. Twig deserves a blog posts of it's own though, so I'll leave it here for today!

Further Reading

Meet our Guest Author
  • Hedley

    Hedley was a founder member of Agile Collective from 2012 - 2014. Now, he lives in the lovely city of Berlin.
Back to blog