How to add Color module support to your Drupal theme

Drupal's Color module (a core module), enables users to change the colours used in a theme through the theme settings. This is a great feature to have if you're developing a theme for widespread distribution, or if you have a large multi-site installation and want individual sites to have different color variations.

If you've attempted to read the Color module documentation, or start implementing it on your own, you're probably confused. Don't worry, you're not alone. There are many things about the way Color module was developed that makes it difficult to understand. 

This article will break down the process of implementing Color module in your theme. It will explain how color module works and outline a step-by-step process for making it work. This article assumes that you have fairly extensive knowledge of Drupal theming.

How does color.module work?

Color module implementation has two main components:

  1. Making color.module apply the colours to your theme
  2. Setting up the admin preview at /admin/appearance/settings/yourtheme to show how the theme will look with the new colours applied.

Color module does a few things when it applies the new colours to your theme:

  1. Replaces hexidecimal colour values in CSS files
  2. Creates sliced images with the new colours for use as CSS background images
  3. Copies unchanged images without alterations

What's this about sliced images, you say? If you're like me, you may be wondering why you would want to do this. Color module was developed years ago for use with the Garland theme. This was before we had png with alpha transparency, and before there was any support for CSS3. In those days, if you wanted to do gradients, opacity, shadows, rounded corners, or alpha transparency, you had to use images.

To create these images, Color module will take a partially transparent base image and layer it on top of a colored background (see Garland's base.png image, for example). The background will be made up of rectangular "slices" of the colors chosen in the theme settings. You can also define one gradient. Then the module will slice this all up into images, which can be referenced as background images in your theme.

This process of slicing images is what makes color module implementation so confusing. However, these days we probably don't need to do this. In fact, if you look at the color module implemetation for the Bartik theme, you'll see that it doesn't use this feature at all. It simply changes hexidecimal color values in a CSS file. Much simpler.

The remainder of this article will describe the process of implementing Color module without sliced images.

To get a better understanding of these two methods for implementing Color module, try applying color settings on a test site for both Garland and Bartik. To see what files were generated by Color module, check to the files/color directory. There you will find folders for both themes. You'll see that Garland generates some images using the new colours as well as two CSS files. Bartik just creates a colors.css file and a logo image.

Examining the implementation of Color module in Garland is a good way to gain an understanding of why this module works the way it does.

Setting up your theme

One thing to keep in mind is that Color module will attempt to change all colour values in the specified stylesheets. For that reason, it's probably a good idea to keep all of the colour values you want to change in a separate CSS file. See Bartik's colors.css file as an example.

Unfortunately, Color module cannot alter colours specified in RGBa or HSL notation. It only works on hexidecimal codes (yes, there's an issue for that).

Implementing Color module

Screenshot of the Color form using Bartik

There are several files that need to be included in your theme for Color module to work. You can see these files in the color/ directory in the Garland and Bartik themes. To get started, you can copy the files from Bartik to your theme directory and change them as described below. 

Step 1: Set up

The file is the cornerstone of your Color module implementation. It contains all of the directions for changing the colours in your theme. 

Define available colors

The $info array is the most important part of this file. Here you define which colors can be changed, the default color scheme, and (optionally), some additional color schemes.

Let's look at the first part of this array:

= array(
// Available colors and color labels used in theme.
'fields' => array(
'top' => t('Header top'),
'bottom' => t('Header bottom'),
'bg' => t('Main background'),
'sidebar' => t('Sidebar background'),
'sidebarborders' => t('Sidebar borders'),
'footer' => t('Footer background'),
'titleslogan' => t('Title and slogan'),
'text' => t('Text color'),
'link' => t('Link color'),

As the comment explains, this section defines the available colors and color labels used in the theme. This is what will show up on the form in the admin screen at admin/appearance/settings/yourtheme.

Change these values to whatever color names you want to use in your theme. The values are set up in key/label pairs. The keys (e.g. 'top') must be lower case with no spaces or special characters. The labels are human-readable names, encased by the t function to facilitate translation.

Keep in mind that "text" and "link" are required. Color module will throw errors if they are not included. Other than that, you can include as many or as few colors as you wish.

Define default & alternate color schemes

The next section of this array defines the default colour scheme for your theme.

// Pre-defined color schemes.
'schemes' => array(
'default' => array(
'title' => t('Blue Lagoon (default)'),
'colors' => array(
'top' => '#0779bf',
'bottom' => '#48a9e4',
'bg' => '#ffffff',
'sidebar' => '#f6f6f2',
'sidebarborders' => '#f9f9f9',
'footer' => '#292929',
'titleslogan' => '#fffeff',
'text' => '#3b3b3b',
'link' => '#0071B3',

The color values listed here should match those used in your colors.css file. This is how color module will know which colors to change and what to replace them with. Each of these values should be unique. Additional color schemes are optional.

Specify which CSS files to alter

There are several other items in the $info array. The 'css' item specifies which CSS files should be altered with the new colours:

// CSS files (excluding @import) to rewrite with new color scheme.
'css' => array(

The path is relative to your theme's directory. As in the Bartik example, this is the colors.css file that contains all the colour values we want to change.

Leave unneeded items blank

If you're using the Bartik (no sliced images) method, the next few items can be left blank. That is, 'copy', 'gradients', 'fill', 'slices', 'blend_target', and (at the end), 'base image'. Do not remove these items from the array. Color module expects them to be there, and you will get PHP errors if they are not included.

If you're like me, you may be wondering why in the world you would want to copy images unchanged. Remember that Color module can change color values in any stylesheets. In the Garland theme, Color module was set up to change all color values in the style.css file. This CSS file includes some background images that don't need to be altered with the new colors. Also remember that Color module creates a new version of the altered CSS file and puts it in the files/color/yourtheme directory. In order for the relative paths to continue to work, the images are simply copied to the new directory.

Files needed for the theme settings preview

Finally, there are some items that define the files used for the preview:

// Preview files.
'preview_css' => 'color/preview.css',
'preview_js' => 'color/preview.js',
'preview_html' => 'color/preview.html',

There are three files listed here for creating the preview for the admin screen at admin/appearance/settings/yourtheme. You'll probably want to leave these the way they are.

If you take a look at Garland's file, you'll notice that it doesn't define a preview HTML or JavaScript file. That's because it's using the default versions included with the Color module. It also defines a preview image – similar to its semi-transparent base image – to be layered with the preview HTML.

Step 2: Add theme functions

In order for Color module to actually work with your theme you need to add a few functions to your theme's template.php file:

* Override or insert variables into the page template.
function yourtheme_process_page(&$variables) {
// Hook into color.module.
if (module_exists('color')) {

* Override or insert variables into the page template for HTML output.
function yourtheme_process_html(&$variables) {
// Hook into color.module.
if (module_exists('color')) {

These functions can simply be copied to your theme's template.php file. Of course, make sure to replace "yourtheme" with the machine name of your theme.

Step 3: Create the the dynamic preview

The final step in implementing Color module for your theme is to create the preview that appears on the theme settings screen. The preview is comprised of an HTML file (color/preview.html) with associated CSS (color/preview.css) that is embedded in the settings page. There is also a JavaScript file that makes the color choices on the form dynamically apply to the preview.

Garland uses Color module's default preview HTML, which is very simple, with a semi-transparent image layered on top. Bartik uses a simplified HTML mock-up of the theme's design.

To create your own, reproduce your design in plain HTML with a separate CSS file. I have had some success with including my theme's CSS file in the preview.css file using @include, but this can have unpredictable results. Keep in mind is that the preview is part of the settings page, and will inherit CSS from the admin theme (Seven, by default). For this reason, it's a good idea to encase your preview HTML in a #preview div, and use that selector in all your CSS declarations (see Bartik's preview.css as an example).

The purpose of the preview is to allow users to get an idea of what the theme will look like with their colors applied. For this reason, your preview doesn't need to look exactly like the real version of your theme.

Since this is a plain HTML file, you won't have access to any of Drupal's output variables that are normally available in template files. For the content, use your theme as the site name and some Lorem Ipsum or other dummy text.

The Preview.js file

The preview.js file makes the color choices in the form dynamically apply to the HTML preview. This makes it possible for the user to instantly see what their site will look like with their colour choices.

If you look at Bartik's preview.js file, you'll see several different things happening. Bartik includes the ability to use the user's uploaded logo in the preview. We will ignore that for this example. At the end of the file it also includes some code to make CSS3 gradients work in the preview. Again, we'll ignore that here. If you want to do either of these things in your theme you can copy Bartik's example.

The remainder of the script contains simple jQuery instructions to apply the value from the color palette form to the relevant selectors in the preview HTML:

JavaScript code from Bartik's preview.js

Repeat this line for all of the CSS properties you want to change in the preview. jQuery's css() property accepts both DOM (e.g. backgroundColor) and CSS formatting (e.g. background-color), so you can use either.


If you've implemented Color module as described above, and the colours still don't apply to your theme when viewed, check your site's files/color directory and make sure a directory is being created for your theme. If it's not, check the file permissions settings on your files/ directory. 

As with many theme issues, some mysterious problems can be solved by clearing the cache.

If you're getting PHP errors, make sure you have not removed any required items from the $info array in your file. Also make sure that you include a base.png and preview.png file (these are required), even if they're not used. Note that Bartik just includes blank images for these files.

Questions or Comments?

To ask questions or comment on this article please see the Webmaster Forums discussion on How to add Color module support to your Drupal theme.

You may also contact me personally, although I can't guarantee a quick response.


Megan McDermott's picture

About the Author

Megan is co-founder and editor of A Padded Cell and administrator at The Webmaster Forums. She has been designing websites since 1997, with expertise in design, information architecture, usability, HTML/CSS, Drupal theming, and more. Megan is also a partner and co-founder of Woolwich Web Works: A small team that can do big things!