New Tools for Drupal 8 Theming: Defining and Using Libraries

Drupal 8 theming has lots of new features, one of the most exciting is the addition of libraries. You can use libraries to add stylesheets and javascript to your theme, globally or in particular situations.

Your Theme's .info.yml File

One of the first steps in creating a Drupal 8 theme is to create the .info.yml file. Your info.yml file is just like a Drupal 7 .info file, except we use the yml instead of ini format.

For example, if your theme is called mytheme, you’ll have a mytheme.info.yml file. At a minimum, your theme mytheme.info.yml will contain the following lines that tell Drupal about your theme:

name: My theme
type: theme
description: 'My first Drupal theme'
core: 8.x

Just like in Drupal 7, you can also define regions in your theme if you want to override Drupal’s default regions:

regions:
  header: 'Header'
  primary_menu: 'Primary menu'
  secondary_menu: 'Secondary menu'
  breadcrumb: 'Breadcrumb'
  help: 'Help'
  content: 'Content'
  sidebar_first: 'Sidebar first'
  sidebar_second: 'Sidebar second'
  footer: 'Footer'

In Drupal 7, we would also list all of our theme's site-wide CSS and JS files in our .info file. But in Drupal 8, we'll use libraries to do this instead.

Libraries

Libraries are groups of assets (CSS and JS files) that you might need for your theme or module. You can add stylesheets and javascript files that you want to use across your entire theme using a ‘global library’.

Libraries are defined in a dedicated file. In our theme, this file will be called mytheme.libraries.yml. To create a global styling library and a search-specific styling library, you would do the following:

global-styling:
  css:
    theme:
      css/styles.css: {}
search-styling:
  css:
    theme:
      css/search.css: {}

Each of these libraries loads a single stylesheet.

Your theme will almost certainly have a global library of CSS and Javascript files that are always loaded (like the global-styling library we created above). To identify which libraries need to be loaded on every page of your site, you'll need to list them in your mytheme.info.yml file like this:

libraries:
  - mytheme/global-styling

You might also have some libraries that are only loaded in certain contexts. For example, some search styling that only needs to be loaded when you’re displaying search results. This could be useful if you have a lot of CSS that applies only to search filters and results.

In this case, in your search page template (page--search.html.twig), you can add the following line of code to attach the search-styling library to that template. Now, each time page--search.html.twig is loaded, the Drupal theme system will ensure that your search-styling library is loaded as well.

{{ attach_library(‘mytheme/search-styling’) }}

Dependencies

One more thing to keep in mind about libraries. Unlike Drupal 7, Drupal 8 doesn't load jquery by default. If you're relying on jquery in your custom library, you'll need to list jquery as a dependency. You can use the same technique to add dependencies on other libraries provided by Drupal core or contrib modules.

search-styling:
  css:
    theme:
      css/search.css: {}
  dependencies:
  - core/jquery

Summing it up

In Drupal 7, we used drupal_add_css to add particular CSS/JS to certain sections of a site, but libraries give us a more controlled and standardized way of doing this. When you’re looking at a new theme, you'll be able to tell at a glance which libraries it defines. Libraries also help to to think through the different contexts that our design needs to implement (e.g. the home page, the search section, the blog). This should prompt us to organize our theme's CSS and JS accordingly so we can minimize the amount of assets loaded on each page.

Blog