In my earlier article, Getting started with jQuery Mobile, I provided an introduction to using the jQuery Mobile framework to build great web experiences for smartphones and tablets. Out of the box, the websites you build with jQuery Mobile look great. Buttons are glossy, gradients are smooth, and the overall interface is elegant.

Depending on your design requirements, however, you may want to blend colors to match your company colors or brand, or highlight or mute buttons and tabs. In short, you may want control of the look and feel of your jQuery Mobile website. This tutorial demonstrates how you can extend the visual structure and themes in a jQuery Mobile website.

jQuery Mobile themes and swatches

jQuery Mobile uses cascading style sheets (CSS) to control the visual layout of content on the screen. There are two main parts of the main jQuery Mobile CSS document:

Structure, which controls the position, padding, and margins for elements such as buttons and tabs on the screen.
Theme, which controls specific visual elements such as fonts, colors, gradients, shadows, and corners. Modifying a theme allows you to control the visual elements of objects such as buttons.

Note: To reduce the use of images (and server requests), jQuery Mobile relies on CSS3 properties to add rounded corners, shadows, and gradients instead of techniques that traditionally required JPEG or PNG images. Buttons, backgrounds, and tab bars are created using CSS. It is possible to use images to control your layout, but this is the exception and not the rule.

Each theme can include one or more swatches. A swatch sets the color values for bars, content blocks, buttons, and list items in a theme. You can use swatches to easily switch among alternative color schemes for the main theme.

The idea behind swatches is to provide quick access to alternate color schemes for a given website. While pages for any website generally apply a consistent color scheme, there are occasions where specific elements on a page need to be highlighted (for example, a Try It button) or de-emphasized (for example, a Not Interested button). Swatches enable you to define and use an alternate color scheme to cover these cases.

The default CSS document that comes with jQuery Mobile has a theme with a set of five swatches that are named a, b, c, d, and e. By convention swatch a is the highest level of visual priority; it is black in the default theme (see Figure 1).

Figure 1. A screen created using the default theme and swatch.

Use of the five default jQuery swatches (see Figure 2) is tied to the following jQuery conventions:

a (black): high-level visual priority
b (blue): secondary level
c (gray): baseline
d (gray and white): alternate secondary level
e (yellow): accent

Figure 2. The five default swatches from a (left) to e (right).

Working with default swatches in jQuery Mobile

Theme control is built directly into jQuery Mobile. Swatches are controlled with the data-theme attribute. If you do not explicitly set data-theme, the default swatch (a) is used. The following code defines a basic page (see Figure 3) using the default color swatch:

        <div data-role="page" id="page">
  <div data-role="header">
    <h1>Sample Page</h1>
  </div>
  <div data-role="content">
    <p>I'm a sample page!</p>
    </div>
</div>

    

Figure 3. A sample page using the default color swatch.

To use a different swatch simply set the data-theme attribute on the page, as in the code below:

        <div data-role="page" id="page" data-theme="e">
  <div data-role="header">
    <h1>Sample Page</h1>
  </div>
  <div data-role="content">
    <p>I'm a sample page!</p>
    </div>
</div>

    

Structurally, the page is the same. The color has changed because the swatch was switched to e using data-theme="e". The header is now a yellow gradient, the background is white fading to light yellow, and the text is a different color (see Figure 4).

Figure 4. The same basic page using swatch e.

By default, all components and visual elements inherit from a swatch that is set on a page. This means you only need to reference the swatch once and all of the components will inherit the new color scheme. In the example code above, the swatch is set for the entire page:

<div data-role="page" id="page" data-theme="e">

You can also independently control the swatch for each individual element (see Figure 5) by setting the element's data-theme attribute, for example:

        <div data-role="page" id="page">
  <div data-role="header" data-theme="c">
    <h1>Header</h1>
  </div>
  <div data-role="content" data-theme="d">
    <p>Content</p>
    <p>&nbsp;    </p>
    <ul data-role="listview" data-theme="b">
      <li><a href="#page1">Page 1</a></li>
    </ul> 
<div data-role="collapsible-set">
      <div data-role="collapsible" data-theme="b">
        <h3>Header</h3>
        <p>Content</p>
      </div>
      <div data-role="collapsible" data-collapsed="true" data-theme="a">
        <h3>Header</h3>
        <p>Content</p>
      </div>
      <div data-role="collapsible" data-collapsed="true" data-theme="e">
        <h3>Header</h3>
        <p>Content</p>
      </div>
    </div>
    </p>
<p>&nbsp;<a href="#page4" data-role="button" data-icon="arrow-d" data-iconpos="left" data-theme="e">Go To Page 4</a></p>
  </div>
  <div data-role="footer">
    <h4>Footer</h4>
  </div>
</div>

    

Figure 5. Swatches set on individual elements.

Creating your own themes

Up to this point you have simply modified your HTML, adding the data-theme attribute to set different color swatches for entire pages or individual elements. This is a good first step, but you may want to go further and control the visual layout of all the content on your page. You can use CSS to control the position, border, padding and other visual effects. The jQuery CSS rules are defined within the jquery.mobile-1.0b1.css file that you reference in the head of your page.

Note: The current version of the jQuery Mobile CSS file (jquery.mobile-1.0b1.css) is for the Beta 1 release. The file name will change for the final release. While the techniques used in this article are expected to work with the final release, you will need to substitute the file name used in the 1.0 release for jquery.mobile-1.0b1.css.

After downloading this file from the jQuery download page, open it in Dreamweaver or your favorite text editor. As noted above, the CSS file defines both theme (color, gradients, fonts, shadows, and so on) and structure (padding and placement of structural elements). Included in the theme section are the five default swatches.

Editing swatches

The swatch sections all share a similar structure. Each swatch is preceded by a comment that identifies the swatch name.

The first CSS class for swatch a is below:

        /* A -----------------------------------------------------------------------------------------------------------*/ 
.ui-bar-a { 
   border: 1px solid #2A2A2A; 
   background:#111111; 
   color:#ffffff; 
   font-weight: bold; 
   text-shadow: 0 -1px 1px #000000; 
   background-image: -moz-linear-gradient(top, #3c3c3c, #111111); 
   background-image: -webkit-gradient(linear,left top,left bottom,color-stop(0,#3c3c3c),color-stop(1,#111111));
   -ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorStr='#3c3c3c', EndColorStr='#111111')"; }

    

The class name (in this case, ui-bar-a ) has a specific structure. The suffix (in this case, a ) identifies the class as part of the a swatch, which can be set using data-theme="a". The ui-bar class controls the footer and header tool bar. It does not use any images. To create visual effects, the class relies on CSS3, including text-shadow and gradient effects. The corresponding class for swatch b is named ui-bar-b. You can create your own swatches by copying the classes for swatch a and replacing the –a in each class name with a suffix of your own as described in Creating your own swatches for jQuery Mobile.

If you're hosting your own jquery.mobile-1.0b1.css file, you can edit the file directly to customize the color scheme. (You'll likely want to make a copy of the file and use that instead.) For instance, the following example changes the text color from black to red in the swatch a header and footer bars:

        .ui-bar-a { 
   border: 1px solid #2A2A2A; 
   background:#111111; 
   color:red; 
   font-weight: bold; 
   text-shadow: 0 -1px 1px #000000; 
   background-image: -moz-linear-gradient(top, #3c3c3c, #111111); 
   background-image: -webkit-gradient(linear,left top,left bottom,color-stop(0,#3c3c3c),color-stop(1,#111111));
   -ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorStr='#3c3c3c', EndColorStr='#111111')"; }

    

Editing other styles

The first 600 lines or so of the CSS document is dedicated to defining the five swatches that come with the default theme. The remainder of the CSS document is used to define general aspects of the theme, such as the roundness of the corners for the buttons. The following example highlights the CSS classes for corner roundness:

        .ui-btn-corner-tl {
   -moz-border-radius-topleft: 1em;
   -webkit-border-top-left-radius:1em;
   border-top-left-radius:1em;
}
.ui-btn-corner-tr {
   -moz-border-radius-topright: 1em;
   -webkit-border-top-right-radius:1em;
   border-top-right-radius:1em;
}
.ui-btn-corner-bl {
   -moz-border-radius-bottomleft: 1em;
   -webkit-border-bottom-left-radius:1em;
   border-bottom-left-radius:1em;
}
.ui-btn-corner-br {
   -moz-border-radius-bottomright:1em;
   -webkit-border-bottom-right-radius: 1em;
   border-bottom-right-radius: 1em;
}
.ui-btn-corner-top {
   -moz-border-radius-topleft: 1em;
   -webkit-border-top-left-radius:1em;
   border-top-left-radius:1em;
   -moz-border-radius-topright: 1em;
   -webkit-border-top-right-radius:1em;
   border-top-right-radius:1em;
}
.ui-btn-corner-bottom {
   -moz-border-radius-bottomleft: 1em;
   -webkit-border-bottom-left-radius:1em;
   border-bottom-left-radius:1em;
   -moz-border-radius-bottomright:1em;
   -webkit-border-bottom-right-radius: 1em;
   border-bottom-right-radius: 1em;
}
.ui-btn-corner-right {
   -moz-border-radius-topright: 1em;
   -webkit-border-top-right-radius:1em;
   border-top-right-radius:1em;
   -moz-border-radius-bottomright:1em;
   -webkit-border-bottom-right-radius: 1em;
   border-bottom-right-radius: 1em;
}
.ui-btn-corner-left {
   -moz-border-radius-topleft: 1em;
   -webkit-border-top-left-radius:1em;
   border-top-left-radius:1em;
   -moz-border-radius-bottomleft: 1em;
   -webkit-border-bottom-left-radius:1em;
   border-bottom-left-radius:1em;
}
.ui-btn-corner-all {
   -moz-border-radius: 1em;
   -webkit-border-radius: 1em;
   border-radius: 1em;
}

    

Each of these classes is generic. They do not reference a specific swatch. In the CSS classes above, each class controls one element of a radius. Inconsistent support of new CSS3 properties across browsers requires that each class have three properties that are essentially the same.

There are hundreds of classes in the CSS file that you can modify to control the look of every visual element on the screen.

Implementing changes

When you are ready to create your own theme or modify the default theme, I recommend that you make a copy of the default CSS document.

Open jquery.mobile-1.0b1.css in a text editor and save the file with a new name; for example: jquery.mobile.theme.css.
Make your changes in the new file. For example, to change the roundness on the headers (see Figure 6), set the radius in the classes listed above (they begin around line 634) to 0.1em.
Save your work.
In your HTML page, change the reference from the default jQuery Mobile CSS document to your new document.

Instructions for testing this on your own device can be found in Testing a theme on your mobile web page.

Figure 6. The headers without rounded corners.

Creating your own swatches

Overall, I find that the default theme settings for jQuery Mobile are very good. What I normally want to change are the swatches.

To change the swatches you have two options. The first is to copy the default CSS document and make your edits as described in the previous section. This can get messy and difficult to manage, particularly if jQuery releases an update to the file.

The second option is to take advantage of the extensibility of CSS and create a second CSS document just for your new swatch. The benefit of this second option is that the original jQuery Mobile CSS file is not modified and your class definition is easier to define.

Create a standalone CSS swatch file

Follow these steps to begin creating a new swatch using the second approach:

Create a new CSS document named jquery.mobile.swatch.i.css.
Open jquery.mobile-1.0b1.css and copy the classes that define swatch a (lines 16–149).
Paste these classes into your new CSS document.
Change the names of each classes, replacing the suffix –a with –i. For example, change all instances of ui-bar-a to ui-bar-i, change ui-body-a to ui-body-i, and so on.
Save your changes.

Modifying the styles

Now you're ready to start modifying the CSS. You're free to make whatever changes you want. In this example, you'll change the background of the button component. There are three main CSS classes that control the style of the button. They are:

. ui-btn-up-i
.ui-btn-hover-i
.ui-btn-down-i

Each of these classes is structured in the same way. Here is the original .ui-btn-down-i :

        .ui-btn-down-i {
    border: 1px solid         #000;
    background:             #3d3d3d;
    font-weight: bold;
    color:                     #fff;
    text-shadow: 0 -1px 1px #000;
    background-image: -moz-linear-gradient(top, 
                            #333333, 
                            #5a5a5a);
    background-image: -webkit-gradient(linear,left top,left bottom,
        color-stop(0,         #333333),
        color-stop(1,         #5a5a5a));
    -ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorStr='#333333', EndColorStr='#5a5a5a')";
}

    

Each button background is styled with a gradient. To change the background colors, change the values of the background, background-image, and -ms-filter properties. For the background-image and -ms-filter properties, you set the starting and ending points in the gradient. For example, to have the gradient transform from light green ( 66FF79 ) to dark green ( 00BA19 ) set those properties as follows:

        .ui-btn-down-i {
   border: 1px solid #000;
   background:#00BA19;
   font-weight: bold;
   color:#fff;
   text-shadow: 0 -1px 1px #000;
   background-image: -moz-linear-gradient(top, #66FF79, #00BA19);
   background-image: -webkit-gradient(linear,left top,left bottom, color-stop(0, #66FF79),color-stop(1,#00BA19));
-ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorStr='#66FF79', EndColorStr='#00BA19')";
}

    

Because different browsers use different mechanisms to apply the gradient, you need to change the colors in three locations. In this example the first background-image property is for Firefox web browsers; the second is for Apple's Safari and Google's Chrome; and the -ms-filter setting is for Microsoft Internet Explorer. While the syntax is slightly different for each setting, the gradients all follow the same pattern: two colors blend with each other, the first color is the start of the blend, and the second color is the end of the blend.

Each jQuery Mobile swatch has more than two dozen different classes you can edit. You do not need to edit them all. In most cases, you can just make a copy of a similar swatch and only edit the properties you want changed.

One great thing about working with jQuery Mobile is that the styles are just CSS. This gives you a great deal of flexibility over the look and feel of your jQuery Mobile sites. For instance, the f swatch included in this article's sample files (jquery-mobile-swatch-f.css) uses @font-face to embed a set of fonts into the page.

Using the new swatch file

There is no limit to the number of swatches you can create (although there is a maximum of 26 swatches per theme). All you have to do is link them to your web page. The following code, for example, links two swatch files, jquery-mobile-swatch-i.css and jquery-mobile-swatch-r.css:

        <link rel="stylesheet" type="text/css" href=" jquery.mobile-1.0b1.css "/>
<link rel="stylesheet" type="text/css" href="jquery-mobile-swatch-i.css"/>
<link rel="stylesheet" type="text/css" href="jquery-mobile-swatch-r.css"/>

    

The final step is to change the value referenced in the data-theme attribute in your HTML. In the following code, the new i and r swatches are used in place of the default theme:

        <div data-role="page" id="page">
  <div data-role="header" data-theme="r">
    <h1>Header</h1>
  </div>
  <div data-role="content" data-theme="i">
    <p>Content</p>
    <p>&nbsp;    </p>

<div data-role="collapsible-set">
      <div data-role="collapsible" data-theme="i">
        <h3>Header</h3>
        <p>Content</p>
      </div>
      <div data-role="collapsible" data-collapsed="true" data-theme="i">
        <h3>Header</h3>
        <p >Content</p>
      </div>
      <div data-role="collapsible" data-collapsed="true" data-theme="i">
        <h3>Header</h3>
        <p>Content</p>
      </div>
    </div>
    </p>
<p>&nbsp;<a href="#page4" data-role="button" data-icon="arrow-d" data-iconpos="left" data-theme="i">Go To Page 4</a></p>
  </div>
  <div data-role="footer" data-theme="r">
    <h4>Footer</h4>
  </div>
</div>

    

Looking ahead to ThemeRoller for jQuery Mobile

Currently, customizing themes and swatches in jQuery Mobile requires editing CSS documents. Moving forward, the jQuery Mobile team is working on a specialized version of ThemeRoller for jQuery Mobile. According to the jQuery Mobile website, a new version of ThemeRoller tool will launch with the jQuery Mobile 1.0 release in 2011.

The original ThemeRoller tool (for jQuery not jQuery Mobile) enables you to easily design a custom jQuery UI theme. For more information, see http://jqueryui.com/themeroller/. Themes and swatches in jQuery Mobile, however, are more efficient than the themes created using the original jQuery ThemeRoller because CSS3 is used throughout jQuery Mobile to control rounded corners, text, drop shadows, background gradients, and more.

While the mobile version of ThemeRoller will certainly make it easier to create themes for your mobile websites it is important to understand how the jQuery Mobile CSS works and how it is structured. Before you use ThemeRoller for jQuery Mobile I encourage you to write your CSS swatch file by hand. The jQuery team has done a great job of making this as easy as possible.

Testing a theme on your mobile web page

To put all the new techniques you've learned in this article into practice, you'll want to create a basic mobile page that uses a custom swatch. You can use Dreamweaver or a text editor to edit the HTML and CSS files. If possible, however, I recommend that you use Dreamweaver to manage a jQuery Mobile site. This will help in editing and managing your files and, later, uploading your files to your mobile website.

If you have a web server, you can host the files and then access them on your mobile device. Otherwise, you can open them directly from your hard drive. I recommend using Chrome for this kind of local testing.

Follow these steps to create a simple page for theme testing:

If you have not already done so, download jquery-mobile-1.0b1.zip from the jQueryMobile.com download page.
Unzip the files and place them in the root folder of your mobile website.
Create a file named test.html. Copy the following HTML into it to create a simple jQuery Mobile page:

        <!DOCTYPE html />
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Sample Page</title>
<link rel="stylesheet" type="text/css" href="jquery.mobile-1.0b1.css"/>
<script src="http://code.jquery.com/jquery-1.6.min.js" type="text/javascript"></script>
<script src="http://code.jquery.com/mobile/1.0b1/jquery.mobile-1.0b1.min.js"></script>
</head>
<body>
<div data-role="page" id="page">
  <div data-role="header" data-theme="e">
    <h1>Sample Page</h1>
  </div>
  <div data-role="content">
    <p>I'm a sample page!</p>
  </div>
  <a href="#page2" data-role="button" data-icon="arrow-d" data-iconpos="left" data-theme="e">Button</a>
</div>
</body>
</html>

    

The first line of HTML above declares the HTML document as a HTML5 document. Older web browsers will still render the page, but will ignore the HTML5 declaration.

Within the HEAD element there is a reference to three files that form the core of jQuery Mobile:

        •	<link rel="stylesheet" type="text/css" href="jquery.mobile-1.0b1.css"/>
•	<script src="http://code.jquery.com/jquery-1.6.min.js" type="text/javascript"></script>
•	<script src="http://code.jquery.com/mobile/1.0b1/jquery.mobile-1.0b1.min.js"></script>

    

The first line refers to the local CSS file; it is possible to use the jQuery hosted version of this file, but not if you're going to make changes to it. The second two are JavaScript files that reference the core jQuery library and jQuery Mobile library, which are both hosted by jQuery.

The BODY element contains the content that will be presented on the screen. You can see that DIV elements are used for the header and content; they are also used for footers and lists. For more details on jQuery Mobile pages, see Getting Started with jQuery Mobile.

Save your changes and view the web page either on your device on in Chrome. You should see the header and button have a yellow background because they are using the e swatch.

To edit a swatch directly as described in Creating your own themes, follow the next four steps.

Make a copy of jquery.mobile-1.0b1.css in your website root and name it jquery.mobile.theme.css.
Open the new file, find the .ui-bar-e class, and change the value of the color attribute from #333 to red :

color: red;

Remove the reference to the original jquery.mobile-1.0b1.css file from your test.html file and replace it with a reference to the new file:

<link rel="stylesheet" type="text/css" href="jquery.mobile.theme.css"/>

Save your changes and refresh the web page in your browser. The text in the sample page header should now be red.

Now, you can apply the swatch in the standalone CSS file you created in Creating your own swatches for jQuery Mobile.

Edit test.html and add a reference to your jquery-mobile-i.css file:

<link rel="stylesheet" type="text/css" href="jquery-mobile-i.css"/>

Change the data-theme value of the button from "e" to "i" :

<a href="#page4" data-role="button" data-icon="arrow-d" data-iconpos="left" data-theme="i">Button</a>

Save your changes and refresh the page. The button should now be green when you click it.

Where to go from here

Knowledge of CSS is vital to creating a great custom jQuery Mobile theme. A great resource for the latest information on CSS is http://www.css3.info/. For a quick reference on CSS3 properties check out the printable cheat sheet from Smashing Magazine.

For more details on jQuery Mobile themes, see the jQuery themes page.

Finally, to get the latest information on jQuery Mobile keep tabs on the jQuery Mobile blog and follow jQuery Mobile on Twitter (@jquerymobile).

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Permissions beyond the scope of this license, pertaining to the examples of code included within this work are available at Adobe.

Tutorials and samples

Tutorials

Samples

Dreamweaver user forum

04/23/2012	Resolution/Compatibility/liquid layout
04/20/2012	using local/testing server with cs5 inserting images look fine in the split screen but do not show
04/18/2012	Ap Div help
04/23/2012	Updating

Dreamweaver Cookbook

11/07/2011	Simple social networking share buttons
09/20/2011	Registration form that will generate email for registrant to validate
08/21/2011	Spry Accordion - Vertical Text - Auto Start on Page Load - Mouse Over Pause
08/17/2011	Using cfdump anywhere you like

Using and customizing jQuery Mobile themes

by Matthew David

Content

Created

Page tools

Requirements

Prerequisite knowledge

User level

Required products

Sample files

jQuery Mobile themes and swatches

Working with default swatches in jQuery Mobile

Creating your own themes

Editing swatches

Editing other styles

Implementing changes

Creating your own swatches

Create a standalone CSS swatch file

Modifying the styles

Using the new swatch file

Looking ahead to ThemeRoller for jQuery Mobile

Testing a theme on your mobile web page

Where to go from here

More Like This

Tutorials and samples

Tutorials

Samples

Dreamweaver user forum

Dreamweaver Cookbook

Products

Solutions

Industries

Help

Learning

Ways to buy

Downloads

Company