Week 3: Add an Asset Library

This is Week 3 of the 7-week course Hands-On: Theming. Get started with Drupal theming in 1 hour a week for 7 weeks. Based on our popular Drupal Theming Workshop featured at DrupalCon.

Time to complete: About 1 hour

This week you will learn about asset libraries in Drupal and how add an asset library to your theme. Go through each tutorial and then apply what you've learned in the final hands-on exercise. Be sure to complete the last tutorial listed (Exercise: Add an Asset Library) before you move on to Week 4: Configure Your Environment for Theme Development.


  1. Understand the various use cases and methods for asset libraries in Drupal.
  2. Complete Exercise: Add an Asset Library:
  • Create a new asset library that includes CSS files from Bootstrap in your custom theme

Sign-up for weekly email reminders

Sign-up for the Hands-On Theming email list and get reminders and tips about each week's exercises!


Own this course

You can also purchase the Practical Drupal Theming course on Thinkific. The course material is the same, but you can access the content without a Drupalize.Me membership and you will own the course forever.

Tutorials in this course
Drupal 8, 9, and 10
More information

An asset library is a bundle of CSS and/or JavaScript files that work together to provide a style and functionality for a specific component. They are frequently used to isolate the functionality and styling of a specific component, like the tabs displayed at the top of each node, into a reusable library. If you want to include CSS and/or JavaScript in your Drupal theme or module you'll need to declare an asset library that tells Drupal about the existence, and location, of those files. And then attach that library to a page, or specific element, so that it gets loaded when needed.

In this tutorial we’ll:

  • Define what an asset library is.
  • Explain why asset libraries are used to include JavaScript and CSS files.
  • Look at some example asset library definitions.

By the end of this tutorial you should be able to define what asset libraries are, and when you'll need to create one.

Drupal 8, 9, and 10
More information

New asset libraries can be defined by either modules or themes. In order to define a new asset library you need to create the requisite CSS and JavaScript files, and a new THEMENAME.libraries.yml, or MODULENAME.libraries.yml file that aggregates them together and provides metadata about the library itself and any dependencies.

In this tutorial we’ll:

  • Look at the structure of a *.libraries.yml file and demonstrate how to combine a couple of CSS and JS files together into an asset library that can be used in a theme or a module
  • Look at how one asset library can declare that it is dependent on another in order to ensure the assets from the dependency are loaded as well

By the end of this tutorial you should know how to define a new asset library in either a module or a theme.

Drupal 8, 9, and 10
More information

Once you've defined an asset library you'll need to tell Drupal when you want to add the CSS and JavaScript that it includes to the page. Ideally you'll do so in a way that allows Drupal to only add the corresponding assets on pages where they are needed.

You can attach a library to all pages, a subset of pages, or to elements in a render array. This allows you to have some assets that are global, and others that get loaded on an as-needed basis. To attach a library you'll need to know both its name and prefix, and then use one of the techniques outlined below to let Drupal know when to include it.

In this tutorial, we'll look at attaching asset libraries:

  • Globally, via your THEMENAME.info.yml file
  • Conditionally, via a preprocess function using the #attached render array property
  • Inside of a Twig template file

By the end of this tutorial you should be able to attach asset libraries in various different ways depending on your use case.

Drupal 8, 9, and 10
More information

You can accomplish a lot without needing to change any markup by adding CSS and JavaScript files to your theme. In this exercise you'll create 2 asset libraries and add them to your theme. Specifically, we want to pull in the CSS and JavaScript from the popular Bootstrap framework so that we can make use of its layout utility classes later on. We'll also add a custom CSS file that contains global styles for our site, like setting the page background color.

If you want to try and complete this on your own first you'll need to:

  • Add the Bootstrap CSS and JavaScript files to your theme.
  • Define an asset library using a THEMENAME.libraries.yml file in your theme.
  • Tell Drupal to attach your asset library so that the CSS and JavaScript files it represents are included in the page.

Once that's done your site won't look all that different. But if you view the page source, or look closely, you should see that the Bootstrap files are included along with any CSS rules you placed into your custom style sheet.

Note: Since this course if focused on teaching the Drupal aspects of theme development, and not on writing CSS, we use the Bootstrap CSS. If you don't need it for your project though you can skip it, or add the CSS framework that you want to use instead.

You should try to complete the exercise steps on your own and use the video to help guide you if you get stuck.

Note: At the end of this exercise, you'll find a video walk-through of the solution.

This course appears in the following guides:
Drupal 8, 9, and 10