Develop Your Own jQuery “ThemeRoller-Ready” Components

Posted by Scott on 06/11/2008

01/11/2009 Note: This article is based upon an version of jQuery UI (v1.5.3). The ThemeRoller CSS Framework has now become the jQuery UI CSS Framework. We will be posting an updated article very soon which will detail the process of developing for the new framework classes. For now, please visit the jQuery UI CSS Framework documentation to find out about developing components with the new framework.

ThemeRoller-ReadyThemeRoller-ReadyEarlier this week we released ThemeRoller, an Ajax-driven theme design app for jQuery UI. Now that the servers have recovered and things are running smoothly, we’d like to uncover a bit of an easter egg that we rolled right into the app: ThemeRoller not only allows you to style the official jQuery UI components, it also provides handy CSS hooks for designing your own ThemeRoller-Ready components! This article will introduce ThemeRoller’s CSS API and show you how to use it in your own projects.

So How Does It Work?

Along with the CSS for jQuery’s component set, ThemeRoller generates a block of classes that can be used to style ANY web application component, even components that don’t use javascript at all! The following demo components are built using ThemeRoller’s component classes. These classes follow the look and feel of any theme you create and even include many assets that jQuery UI’s components don’t use.

Example: A ThemeRoller-Ready Button

Demo page

The button above uses these ThemeRoller classes, almost exclusively, for its appearance. To make the button ThemeRoller-Ready, we assigned it a class of ui-default-state, and on mouseover we added the class ui-hover-state. That alone makes it ready to accept ThemeRoller styles! From there we simply imported a ThemeRoller-generated stylesheet and added 2 styles for some padding and a hand cursor.


<button type="submit" class="ui-default-state" name="submit">Submit Button</button>


@import('jquery-ui-themeroller.smoothness.css'); /*ThemeRoller CSS*/
.ui-default-state { padding: .5em 1em; cursor: pointer; }



More ThemeRoller-Ready Components

The following components use ThemeRoller classes in a similar fashion to the button above.

Button Bar

Demo page


<ul id="buttonBar" class="ui-reset ui-clearfix ui-component ui-hover-state">
    <li><a href="#" class="ui-default-state">Nav Item</a></li>
    <li><a href="#" class="ui-default-state">Nav Item</a></li>
    <li><a href="#" class="ui-default-state">Nav Item</a></li>
    <li><a href="#" class="ui-default-state">Nav Item</a></li>


@import('jquery-ui-themeroller.smoothness.css'); /*ThemeRoller CSS*/
.ui-default-state { padding: .5em 1em; cursor: pointer; }
#buttonBar { background-image: none; padding: 0; }
#buttonBar li, #buttonBar li a { float: left; margin: 0; padding: 0; list-style: none; text-decoration: none; }
#buttonBar li a  { padding: .5em 1em; border-width: 0; margin: 1px; text-decoration: none; display: block; }

Jump Menu

Demo page


<div id="jumpMenu" class="ui-component">
    <a href="#menu" id="trigger"class="ui-default-state"><span class="ui-arrow-down-default">Menu</span></a>
    <div id="menuContain">
        <ul id="menu" class="ui-active-state">
            <li><a href="#">Nav Item</a></li>
            <li><a href="#">Nav Item</a></li>
            <li><a href="#">Nav Item</a></li>
            <li><a href="#">Nav Item</a></li>


@import('jquery-ui-themeroller.smoothness.css'); /*ThemeRoller CSS*/
.ui-default-state { padding: .5em 1em; cursor: pointer; }
#trigger { text-decoration: none; display: block; width: 4em; position: relative; z-index: 2; }
#trigger span { padding-right: 1.3em; background-position: right 50%; margin-right: 3px; }
#trigger.ui-active-state { border-bottom: 0; }
#menuContain { position: relative; z-index: 1; }
#menu { position: absolute; width: 15em; background-image: none; padding: 0; list-style: none; margin: 0; top: -1px; }
#menu li a  { padding: .5em 1em; border: 0; text-decoration: none; display: block; cursor: pointer; }

Think of it as a CSS Component Framework

The additional styles generated by ThemeRoller can be thought of as an API to the themes it generates. The following table lists the ThemeRoller classes, their intended purposes, and what they look like.

ThemeRoller Class Documentation

Change Theme Below image image image image image image image image image image image





Component container element class. Sets font family and size…




For content areas and menus in UI components.


.ui-component-content a

For links within content areas.




Default state for clickable items, title bars, etc.


Hover state for clickable items, title bars, etc.


Active state for clickable items, title bars, etc.



Right arrow icon default state.


Right arrow icon hover state.


Right arrow icon active state.


Left arrow icon default state.


Left arrow icon hover state.


Left arrow icon active state.


Down arrow icon default state.


Down arrow icon hover state.


Down arrow icon active state.


Up arrow icon default state.


Up arrow icon hover state.


Up arrow icon active state.


Up arrow icon default state.


Up arrow icon hover state.


Up arrow icon active state.


Left-Right Arrows icon default state


Left-Right Arrows icon hover state


Left-Right Arrows icon active state


Up-Down Arrows icon default state


Up-Down Arrows icon hover state


Up-Down Arrows icon active state


Close icon default state


Close icon hover state


Close icon active state


Folder closed icon default state


Folder closed icon hover state


Folder closed icon active state


Folder open icon default state


Folder open icon hover state


Folder open icon active state


Document icon default state


Document icon hover state


Document icon active state


Minus icon default state


Minus icon hover state


Minus icon active state


Plus icon default state


Plus icon hover state


Plus icon active state

Helper Classes


Hidden elements



Accessible version of hidden elements



Reset styles



Clearfix styles


ThemeRoller-Ready Coding Pointers

This system is new to us as well, but in the short time we’ve experimented with it, we’ve come across some interesting and useful tips to share. Here are some handy tidbits to consider.

ThemeRoller Javascript Tips

Setting Global Hover States

If you noticed, the jQuery behind our button example contains a selector for the ‘.ui-default-state’ class. It finds elements with this class and adds the ThemeRoller hover class on mouseover, and removes it on mouseout. This is particularly handy because it talks to every element with that class, essentially driving all of your ThemeRoller-Ready element states in one command. However, be careful to scope it appropriately to prevent ThemeRoller-classed elements that should not have a hover state, such as a title bar in a modal box.

ThemeRoller CSS Tips

Keep Your Styles as Structural as Possible

This means leaving all colors, font info, and backgrounds out of your custom styles. Anything that can be styled should receive ThemeRoller theme styles.

Try to Make Visual Connections

It’s common for ThemeRoller themes to have identical Active and Content states. When this occurs, components like tabs and the jumpmenu above can make smooth connections between clickable elements and their content areas. To do this, try overriding your active state class by setting its bottom border width to 0. Then, with a negative bottom value (bottom: -1px;), you can pull corresponding content right underneath the clickable element. See our jumpmenu above or jQuery UI’s tab control for an example.

Use CSS Overrides

You might have noticed that although we’re using the ui-default-state class with the buttons in the button bar, the buttons don’t have the border color that comes with that class. In our custom styles, we’ve overridden the border style and used a margin instead, allowing the bar background to show through as a border on the buttons. We did this to eliminate the thick outlines that would appear when using borders on so many elements.

This border/margin technique isn’t very interesting in itself, but we discovered while building it that you can override styles in ways that are less harmful to your component’s Theme-ability. Using this border example, we could have simply written border: 0; to achieve our effect. But instead, we used border-width: 0;, which only overrides the border’s width while keeping its style and color in memory. This might come in handy later if we decide we’d like one of the buttons to have a right border and would like it to use our theme’s color.

There are additional patterns in setting your overrides that will allow you to retain portions of a theme you might need later. For example, you might want to use a certain ThemeRoller class for one of its rules, but then override the others. Generally, it is a good idea to write your override styles with the most specific rule possible. Some examples would be using background-color or background-image rather than background.

Just For Fun… Live Theming!

All 3 of the demo components are shown below so you can see how one css file cascades through all of them and changes their appearance. You can even paste in any ThemeRoller URL in the input below to update the theme to one you’ve created. Go wild! Note This little demo seems to be quirky in Safari; try in Firefox.

Demo page

ThemeRoller-Ready Badges!

When you create a ThemeRoller-Ready component, you can post one of these badges with it on your site to show developers that it’s compatible with ThemeRoller.

ThemeRoller-Ready ThemeRoller-Ready ThemeRoller-Ready ThemeRoller-Ready

Download all 4 (ZIP 30kb)

Go Give It a Try!

We’re really excited at the potential of these ThemeRoller classes. jQuery has an incredible developer community and with plugins constantly being created, it would be incredibly helpful if developers could start making their components ThemeRoller-Ready. We encourage you to try it out and if you have any feedback or questions, please leave us a comment below. Enjoy!



<div id="commentNumber1" class="commentEntry">
<p>I never thought of styling an entire website with Theme Roller themes, this is hot.

    <p class="posted"><a href="#commentNumber1">Comment</a> by

Marc Grabanski on 06/13  at  02:01 PM

<div id="commentNumber2" class="commentEntry">
<p>Very cool! Great concept.

    <p class="posted"><a href="#commentNumber2">Comment</a> by

Aaron Lee on 06/18  at  04:26 AM

<div id="commentNumber3" class="commentEntry">
<p>Great! I think I can use this concept in my project. thanks!

    <p class="posted"><a href="#commentNumber3">Comment</a> by

spawn li on 07/07  at  05:02 AM

<div id="commentNumber4" class="commentEntry">
<p>I think this is great.&nbsp; Say you wanted to style more than just the widgets in a page, though.&nbsp; Do you have any plans on expanding the css classes you have to include more elements or more widgets?

For example, you have a box in one of your sidebars on your webpage.  Right now, the closest thing you have to a box is the ui-dialog* classes.  It would be great to have a ui-box* set of classes, too, or something to that effect.

The reason for asking is not so much for jquery, but if this was something to build a whole theme for, it seems like you would need some more, generic classes along with the good ones you have defined.

I hope Im making question clear.

Jesse Foster | jf26028

    <p class="posted"><a href="#commentNumber4">Comment</a> by

Jesse Foster on 07/07  at  10:04 PM

<div id="commentNumber5" class="commentEntry fg">
<p>@Jesse: Thanks for commenting. Glad you like it.

The ThemeRoller styles do include a few classes for stateless content areas in an app, such as ui-component-content, which you could use to style container elements on a site. That class doesn’t come with a lot of configurable styles though, so the most it will do is a add a background color, border, and font color; it’s meant to be the class used on container elements within a widget, such as a tab pane.
Overall, the classes are more geared towards widgets within an application rather than the entire layout. The immediate goal is to help standardize jQuery plugin development (CSS-wise) so that plugins in the wild are easier to integrate into an existing design. It seems more common for widgets to be reused in this way as opposed to entire website layouts, with the exception of blog themes or something like that.
Anyway, I agree that it could be interesting to explore some more global options. But the tool may need a few more levers added to make it flexible enough for custom layout designs.

    <p class="posted"><a href="#commentNumber5">Comment</a> by

Scott (Filament) on 07/09  at  09:46 AM

<div id="commentNumber6" class="commentEntry">

That makes sense.  I like what you guys are doing, and Im trying to (unfortunately) extrapolate it out into this global framework for building entire sites, when that is not necessarily the scope of your project.

I do agree with you, though, that a set of classes could be utilized to create an infrastructure for things like blogs or forums, where there are common ui entities, while an all encompassing sort of framework would be a lot trickier to pull off.

Anyway, I like what you guys have here.  I may attempt a blogengine theme here soon using this toolset, just to see how it goes.

Thanks, again, for your insight,

Jesse Foster | jf26028

    <p class="posted"><a href="#commentNumber6">Comment</a> by

Jesse Foster on 07/09  at  01:35 PM

<div id="commentNumber7" class="commentEntry">
<p>Two questions:

1. Do the skinning capabilities also include shape? I’m guessing the lack of rounded corners was a deliberate decision.

2. Are there any plans to extend the support to other UI elements? For example, YUI has a much broader range of button types, though their skinning system is quite a bit more cumbersome.

Great project — looking forward to seeing it continue to develop!

    <p class="posted"><a href="#commentNumber7">Comment</a> by

Chad T. on 09/16  at  08:54 PM

<div id="commentNumber8" class="commentEntry fg">
<p>@Chad: Thanks, glad you like!

Currently, we don’t have an option in ThemeRoller for corner radius, but it would make a nice addition. We considered rounded corners when we were designing UI’s component themes but it would have added a lot of overhead in markup so we opted out. Perhaps we can do it using CSS border-radius for the newer browsers, though.

As for your second question, the jQuery UI team is continuing to add new components to the set. They actually came out with some new components this week. We’ll get them into ThemeRoller as soon as we can!
Beyond that, we’re looking to the jQuery community to develop more UI elements and components using the ThemeRoller framework. Help us spread the word! :-)

    <p class="posted"><a href="#commentNumber8">Comment</a> by

Scott (Filament) on 09/23  at  12:04 AM

<div id="commentNumber9" class="commentEntry">
<p>Great Stuff.

I have a question:
Is it possible to use such a interface as :
to theme my private website from backoffice. I mean I download script of themeroller(js,php) on back office and then theme the main webpage for user.
If so:
1. Where can I download such a script?
2. Is is possible to use it for commercial use?

Thanx in advance

    <p class="posted"><a href="#commentNumber9">Comment</a> by

mike on 11/14  at  11:05 AM

<div id="commentNumber10" class="commentEntry">
<p>I’m using a Themeroller generated theme on a site we’re developing and we had a problem with the button layout on the jQuery UI dialog. On IE6/7, the button page was shifting way off to the right, outside of the dialog. After a little trial and error, I added a left: 0; to the jquery-ui-themeroller.css file, so it now looks like this:

.ui-dialog-buttonpane {
position: absolute;
bottom: 0;
width: 100%;
text-align: left;
border-top: 1px solid #707c5a;
background: #faf7eb;

I hated editing generated code because we may need to generate it again at some point. Is this a legit problem or was there a better way we should handled it. I realize I could have set that value in our site CSS, but I’d prefer it to be in one spot.

Here are the before and after pics to show you what I’m talking about:

    <p class="posted"><a href="#commentNumber10">Comment</a> by

Chris Palmer on 12/10  at  12:18 PM

<div id="commentNumber11" class="commentEntry">
<p>Great work!&nbsp; I’m excited to start using ThemeRoller and JQuery UI in my projects.&nbsp; A couple of questions:

1) Your “button bar” example above uses the “ui-reset” and “ui-clearfix” classes but ThemeRoller doesn’t seem to generate these classes.  Looking at the “Themeroller Class Documentation” section, all of the helper classes are listed as “N/A”.  How do I get Themeroller to generate these classes?

2) What is the proper way to integrate ThemeRoller css files with the already provided JQuery UI css files?  It appears I still need to include the “ui.all.css” file (or appropriate core and widget css files) and then include the ThemeRoller css file, correct?

    <p class="posted"><a href="#commentNumber11">Comment</a> by

Chris Leonello on 01/07  at  09:50 AM

<div id="commentNumber12" class="commentEntry fg">
<p>The content of this article is now outdated and only applies to jQuery UI version 1.5.3. jQuery UI 1.6 rc4 is now out and it includes a brand new CSS Framework that is built to not only handle jQuery UI’s widgets, but also your custom jQuery components as well. It is quite similar to the techniques described in this article but is much more full-featured now and a lot has changed. We will be updating the jQuery docs with information on using the new framework as soon as we can, but for now you can visit our planning wiki to find out about the CSS Framework classes now available.

Visit the wiki page here:
We’ll rewrite this article soon with plenty of details about the new framework.

@Chris: The information you are looking for should be in my comment above and those classes are now included in ui.core.css. The theme-related classes are in a file called ui.theme.css and the plugins all have individual css files as well, such as ui.datepicker.css. Note that currently ThemeRoller is only generating ui.theme.css with its downloads, so you’ll have to get the other static files manually (you can get them by downloading this zip and pull the files from themes/base folder from there (just use ui.theme.css and images that ThemeRoller generates). We should have this fixed today so that ThemeRoller includes all necessary files. Thanks!!

    <p class="posted"><a href="#commentNumber12">Comment</a> by

Scott (Filament) on 01/07  at  10:11 AM

<div id="commentNumber13" class="commentEntry">

Thanks for the quick reply.  I am using 1.6rc4 and did find the necessary classes in theme/base (with some minor name changes).  I didn’t see you post ‘till just now, it would have saved me some time ;-(

Keep up the excellent work!  I’m migrating a UI from ExtJS to JQuery and it is amazing how many fewer lines of code I have!  Plus, your themes are very cool!

    <p class="posted"><a href="#commentNumber13">Comment</a> by

Chris Leonello on 01/07  at  02:10 PM

<div id="commentNumber14" class="commentEntry fg">
<p>@Chris: Sounds great. We’d love to see a link to anything you end up building with the framework.

    <p class="posted"><a href="#commentNumber14">Comment</a> by

Scott (Filament) on 01/07  at  02:23 PM

<div id="commentNumber15" class="commentEntry">
<p>Hi Guys,

I am looking forward to being able to skin an entire site + components with the themeroller.  Not much luck so far though and I eagerly await the updated article.  I am able to get to a point (use the themes via the ui.theme.css classes but am not able to get the rollovers happening. I have gone through each class to experiment with the look but it is not coming together easily.  The button bar example for the latest themroller is the one I am most interested in. 
Thanks in advance,

    <p class="posted"><a href="#commentNumber15">Comment</a> by

BC on 01/23  at  05:31 PM

<div id="commentNumber16" class="commentEntry">
<p>@B and anyone else like me who could not implement this particular mentioned themeing method.

I went to the recent articles and clicked on the first one titled “Styling Buttons and Toolbars with the jQuery UI CSS Framework”

They provided a slight variant to the above mentioned which solved my problem hands down. I downloaded and renamed all the theme folders and pointed to ui.all.css

Here is what changed:
class=’ui-default-state’ => class=’ui-state-default’
$(this).addClass(’ui-hover-state’); =>$(this).addClass("ui-state-hover");
$(this).removeClass(’ui-hover-state’); =>$(this).removeClass("ui-state-hover");

I may have missed something and this was done on purpose but for me this worked out much better.

- Jeff C.

    <p class="posted"><a href="#commentNumber16">Comment</a> by

Jeffrey Clak on 02/04  at  06:25 PM

<div id="commentNumber17" class="commentEntry">
<p>Can you please update the example for jQuery UI 1.7 ?

Thanks a lot for your magnific work.


    <p class="posted"><a href="#commentNumber17">Comment</a> by

haichen on 03/14  at  08:37 AM

<div id="commentNumber18" class="commentEntry">
<p>I got it now:

1. first I made a custom theme with themeroller.
2. I extracted the files in the same dir as the themeswitcher.html.
3. then I changed the css and js in the header
<link type="text/css" href="css/smoothness/jquery-ui-1.7.custom.css" rel="nofollow" rel="Stylesheet" />

5. I made the changes according to Jeff C. 
4. the buttonbar has to look like this:
<ul id="buttonBar" class="ui-helper-reset ui-helper-clearfix ui-widget ui-state-default">
<li>Nav Item</li>
5. at last i linked to the custom css in in the themelist

Maybe this is helpful to somebody

    <p class="posted"><a href="#commentNumber18">Comment</a> by

haichen on 03/17  at  06:51 AM

<div id="commentNumber19" class="commentEntry">
<p>Excellent work. Its for new web generation.

    <p class="posted"><a href="#commentNumber19">Comment</a> by

Guru on 03/26  at  01:45 AM

<div id="commentNumber20" class="commentEntry">
<p>i cannot read it because my english isnot good

and i don’t konw how to get start
i was interested in the color picker may be you can send me a pocker about it
i don’t know if you can understand my mean
thank you very very much!!

    <p class="posted"><a href="#commentNumber20">Comment</a> by

crazycode on 03/30  at  10:25 PM

<div id="commentNumber21" class="commentEntry">

Would like to introduce my themeroller ready datagrid.

It can be found at

Thanks for great css skins!


    <p class="posted"><a href="#commentNumber21">Comment</a> by

Olav Chr. Botterli on 09/18  at  10:27 AM

<div id="commentNumber22" class="commentEntry fg">
<p>@Olav  Good use of the framework. You should add in the theme switcher menu to really show off the themeability - just drop in a line of code and it will inject all the gallery themes in a dropdown menu:

    <p class="posted"><a href="#commentNumber22">Comment</a> by

Todd (Filament) on 09/18  at  10:42 AM

<div id="commentNumber23" class="commentEntry">
<p>Brilliant tool. Better than my best dreams.

    <p class="posted"><a href="#commentNumber23">Comment</a> by

Janos on 12/04  at  05:32 AM

<div id="commentNumber24" class="commentEntry">
<p>Great script. useful for us.

    <p class="posted"><a href="#commentNumber24">Comment</a> by

PradeepKr on 09/03  at  03:15 PM

<div id="commentNumber25" class="commentEntry">
<p>The red box at the top mentions a new article will be available very soon, but the date on the note is over one year old.&nbsp; Is there another article available somewhere?

    <p class="posted"><a href="#commentNumber25">Comment</a> by

Russ Ryba on 10/13  at  08:14 AM

<div id="commentNumber26" class="commentEntry">
<p>Thanks for the share, I have been reading online all day and this was

actually worth reading.I’ll love to read more from your side… Thanks :)

    <p class="posted"><a href="#commentNumber26">Comment</a> by

Ped Egg on 12/15  at  02:38 AM

<div id="commentNumber27" class="commentEntry">

I’ve been trying to extend Theme Roller on my own and this really helps.

    <p class="posted"><a href="#commentNumber27">Comment</a> by

Anne on 05/24  at  09:23 AM