How to Add Stylesheets to Your Theme

Posted: October 6, 2011 under CSS, Drupal

Adding stylesheets to a web page is one of the first things a designer or developer learns how to do, but adding a stylesheet the "Drupal way" calls for a different approach. In my rush to finish the custom theme for my first Drupal site, I skipped the documentation on adding CSS and simply placed a link to the stylesheet in the page.tpl.php template file.

It's a little embarrassing to admit this mistake now, but it wasn't such a bad guess, really. After all, adding styles to a template file is the preferred method in other flavors of web development. But by adding my CSS in this way, I bypassed Drupal's stylesheet aggregation and compression, and in doing so, lost a nice little performance boost

Now that you know how you shouldn't add your styles, here are three ways to correctly add them to your Drupal theme.

The .INFO File

Probably the easiest way to add a stylesheet to a theme is to include it in the .INFO file. To do this, simply add the following code:

stylesheets[all][] = style.css

The above will add a stylesheet named 'style.css' for all media types. Note the empty brackets after the media type 'all'. They should always be included and they indicate that each stylesheet is to be added to an array. Adding a style for another media type, for example 'print', is exactly the same, just change the CSS media type in the first brackets:

stylesheets[print][] = print.css

There are downsides to adding styles in the .INFO file, however. For one, the styles you add there will be loaded for every page, something you may not want if you're trying to optimize performance. You also can't add conditional stylesheets for Internet Explorer without using the Conditional Stylesheets module. Luckily, there are alternatives.

drupal_add_css()

The drupal_add_css function is the primary way of adding stylesheets via code. Typical uses of this function are adding styles for a custom module or adding a stylesheet conditionally. In the admittedly contrived example below, I add a stylesheet called 'authenticated-users.css' for logged in users. Note that the function should be placed in the template.php file which is located in your theme folder.

  1. <?php
  2. function YOURTHEME_preprocess_html(&$variables) {
  3. // An anonymous user has a user id of zero.
  4. if ($user->uid > 0) {
  5. drupal_add_css(path_to_theme() . '/css/authenticated-users.css',
  6. array('group' => CSS_THEME));
  7. }
  8. }

The first parameter is the path to the CSS file and the second is an array that can include a number of different values. In this case I've added it to the CSS_THEME group which serves to give it a weight. Higher weight stylesheets take precedence over those in lower weight groups. The function documentation details all the many options that are available for the two parameters.

Although very useful, this method is not without its drawbacks, either. It causes a performance hit because the aggregated stylesheet has to be rebuilt. There is a comment from John Albin Wilkins (another of my top Drupal developers) on a way to include conditional styles without the performance hit that I recommend reading.

hook_css_alter()

So before getting into exactly what this function does, let's review the idea of a hook. This terminology isn't very intuitive for those new to Drupal or programming in general, but it's a pretty straightforward concept.

A hook is simply a function that you can use in your custom module or theme to interact with Drupal core. Think of them as places you can override the default behavior of other modules or themes. When implementing a hook, you always take out the 'hook' part of the function name and replace it with the name of your custom theme.

The hook_css_alter function is often used to override the default CSS provided by other modules and themes. There is a great example of the use of this function in a comment by Nicolas Long in the documentation page for the function. The example he cites is from the Tao theme and demonstrates how to remove stylesheets that were included by core modules. I've included an abridged version below:

  1. <?php
  2. function tao_css_alter(&$css) {
  3. $exclude = array(
  4. 'misc/vertical-tabs.css' => FALSE,
  5.  
  6. // More code here...
  7.  
  8. 'modules/user/user.css' => FALSE,
  9. ); $css = array_diff_key($css, $exclude);
  10. }
  11. ?>

Note that 'hook' was replaced by the the name of the theme, 'tao'.

Wrapping It Up

Most of the time, adding stylesheets to your custom Drupal theme will be accomplished the quick and easy way using the .INFO file. But take the time to check out the extra power and flexibility you get from setting your styles through code, particularly drupal_add_css. Of course, it's important to use the best method for each situation. Fortunately Drupal provides developers with several good options.

About the Author

John Hannah

I’m John Hannah, a front end developer at Lullabot . When I'm not building websites, I travel as much as possible and enjoy hanging out with my wonderful family. My favorite place to spend my coffee breaks is Twitter, so please feel free to connect with me there.