facebook twitter
Webucator's Free jQuery Mobile Tutorial

Lesson: The Theme Framework

Welcome to our free jQuery Mobile tutorial. This tutorial is based on Webucator's jQuery Mobile course.

jQuery Mobile offers an extensive theme framework, allowing you the convenience of selecting from preexisting styles - based on well-established design patterns optimized for mobile use - but also the ability to customize the layout and style of your sites.

Lesson Goals

  • Learn how to use jQuery Mobile's ThemeRoller to generate styles.
  • Learn how to create and use custom icons.
  • Learn how to use CSS to create custom layouts and styles for your sites.

Themes in jQuery Mobile

jQuery Mobile themes are set via external CSS stylesheets. Themes consist of settings both for global style attributes - the radius of rounded corners, the color for the on-state of buttons, etc. and up to to 26 "swatches" (lettered from A to Z), each with a unique color scheme. Swatches define the colors, font settings, and textures for elements such as toolbars, content blocks, and buttons. jQuery Mobile recommends building themes with at least three swatches, A to C.

Without any overriding settings, jQuery Mobile uses the stock theme "a" swatch (a light-colored swatch) for most elements. In our work so far, the CSS rules for these swatches have come from the CDN-hosted CSS file we have included in the head of each of our jQuery Mobile. (For performance improvements, we've included the minified CSS file in all of our pages - here's the complete uncompressed CSS.) This default "a" swatch's CSS for toolbars includes, in part, this rule:

.ui-page-theme-a .ui-bar-inherit,
html .ui-bar-a .ui-bar-inherit,
html .ui-body-a .ui-bar-inherit,
html body .ui-group-theme-a .ui-bar-inherit {
background-color: #e9e9e9 /*{a-bar-background-color}*/;
border-color: #ddd /*{a-bar-border}*/;
color: #333 /*{a-bar-color}*/;
text-shadow: 0 /*{a-bar-shadow-x}*/ 1px /*{a-bar-shadow-y}*/ 0 /*{a-bar-shadow-radius}*/ 	#eee /*{a-bar-shadow-color}*/;
font-weight: bold;

The background color (background: #e9e9e9) is light and the text color (color: #ddd) is dark.

In versions prior to 1.4, jQuery Mobile offered a set of five (lettered "A" through "E") swatches. Version 1.4 reduced that set to two: the "A" swatch (a light-background, dark-text theme) and the "B" swatch (a dark-background, light-text theme). The screenshot below shows the difference between the stock "A" and "B" swatches:

A vs B themes

Use the attribute data-theme="a" (or "b") to set any elements' theme: you can set pages, bars, listviews, buttons, and form elements to have a specific theme swatch. Contained elements inherit the theme swatch of their parent container.

For elements whose style is specified via CSS class, use the corresponding class to render the element by theme. For instance, an anchor (a) tag is rendered as a button with class="ui-btn"; use class="ui-btn ui-btn-b" to set swatch "B" for the button.

Using Default Theme Swatches to Style Pages & Elements

Duration: 15 to 20 minutes.

In this exercise, you will use the default jQuery Mobile theme to style pages and elements.

  1. Open ThemeFramework/Exercises/swatches.html in a file editor.
  2. Add a listview to the #home page; style it with swatch "b" as shown:swatch exercise
  3. Style #page2 with swatch "b". Add a button, linking to the #home page, at the bottom of #page2; style this home button with swatch "a". The result should look like this:swatch exercise
  4. Add a form to #page3 with a text input and a set of three checkboxes: style the text input as "a" and the checkboxes as "b":swatch exercise



Code Explanation:

On the #home page, we add data-theme="b" to the listview.

We add data-theme="b" to #page2; note how the page elements (those not otherwise explicitly styled) inherit the swatch color. The button at bottom gets a class of ui-btn-a.

We style the individual form elements on #page3 with various swatch letters to produce the desired visual look.


The default jQuery Mobile theme offers a considerable degree of customization options, but the range of colors and style are, of course, limited. What if we want to add our own colors? And what if we want to change the font or the dropshadow color or roundedness of buttons?

For this we turn to ThemeRoller, a powerful, free, what-you-see-is-what-you-get UI builder available on the jQuery Mobile website. ThemeRoller offers a visual interface from which we can set a variety of color, font, and other options to define our own custom theme; once happy with our design, we can download a single CSS file, link to it in our pages, and thus apply the design choices to our sites.

Open up ThemeRoller in your browser to try it out:

ThemeRoller Interface

The "Help" docs (via the link at upper right) offer a helpful overview of the interface:

The ThemeRoller interface has three major zones: the left column contains the inspector panel, along the top is the QuickSwatch/Kuler bar, and below this is the preview window.

Use the inspector pane to set global theme settings on the first tab and tweak the individual style options for each swatch. Above the tabs, there are links to download, share, or import a theme.

In the QuickSwatch bar, you can turn the inspector feature on to automatically expand the relevant inspector section when you click on an element in the preview pane. Drag and drop a color from the QuickSwatch panel onto an element in the preview pane and the tool with automatically calculate text color and shadow, borders, gradients and even button states. The sliders make it easy to adjust the lightness and saturation of the colors. Click the Adobe Kuler Swatches to load premade color palettes from Adobe's popular color palette sharing site.

The preview pane shows a sample of common jQuery Mobile widgets that shows a live update each time you make a change to the theme so you can quickly test and tweak the theme.

When using ThemeRoller, you can either set color options by typing hex codes or by dragging a color onto the element. Similarly, you can type explicit values for the roundedness of corner or drag a slider.

Adobe Color

ThemeRoller offers convenient integration with Adobe Color (formerly known as "Adobe Kulur" - ThemeRoller stills bears the old name), a free online color-theme-generation tool. To use Adobe Color, login with a valid Adobe account (register for free, if needed). Once logged in, you can search and browse public themes - filtering by "newest", "highest rated", or other criteria - or create your own. I created a theme ("Webucator JQM") you can view online - I'll use it in the demo below.

ThemeRoller Interface

With Adobe Color you can create a theme from an uploaded or Flickr-stored image or from a specific base color. You can select rules ("analogous", "triad", etc.) from color theory to generate the scheme, drag axes around a color wheel, or set colors explicitly with HSV, RGB, Hex, or other settings.

Once you create an Adobe Color theme, you can use its colors in ThemeRoller, adding them to toolbars, buttons, or other elements as desired. To use a saved Adobe Color theme from within ThemeRoller:

  1. Click the "Adobe Kuller swatches" link at the top of ThemeRoller.
  2. Choose "Search Title" from the drop-down.
  3. Enter (in this case) "webucator" as the search term.
  4. Click each color square to add it to ThemeRoller's "Recent Colors" palette, from which you can use the colors in desired elements of the theme.

Let's look at an example. We used the colors from the Adobe Color theme we created above to render a custom theme in ThemeRoller. While it might offend some folks' artistic sensibilities, the process works quite nicely:

ThemeRoller theme from Adobe Kuller Webucator pallette

We click "Download theme zip file" at the top of the ThemeRoller interface, save the .zip file, and unpack the .zip archive. We edit the index.html file to include our standard Nan & Bob's content - including, in this case, some widget and form elements to highlight the theme's color style rules. Here's the resulting page - easily styled as desired with minimal coding:

themed site

Code Sample:


Code Explanation:

The only work we need to do here to make the custom theme work is to get the linked stylesheets right. We link to the downloaded (and conveniently minified) stylesheet, themes/webucator.min.css. Also, instead of linking to the standard jQuery Mobile stylesheet (jquery.mobile-1.4.5.min.css), we instead link to the (also CDN-hosted) "structure" stylesheet: jquery.mobile.structure-1.4.5.min.css. This ensures that we get the CSS we need to "run" jQuery Mobile, but without the default color/font/etc. theme; we now get these style rules from our custom, downloaded stylesheet.


As we've seen, jQuery Mobile comes with 50 stock icons out of the box, corresponding to the data-icon="[icon-name]" attribute:

jQuery Mobile Button Icons
Icon Code
Action Icon action
Alert Icon alert
Arrow-D Icon arrow-d
Arrow-D-L Icon arrow-d-l
Arrow-D-R Icon arrow-d-r
Arrow-L Icon arrow-l
Arrow-R Icon arrow-r
Arrow-U Icon arrow-u
Arrow-U-L Icon arrow-u-l
Arrow-U-R Icon arrow-u-r
Audio Icon audio
Back Icon back
Bars Icon bars
Bullets Icon bullets
Calendar Icon calendar
Camera Icon camera
Carat-D Icon carat-d
Carat-L Icon carat-l
Carat-R Icon carat-r
Carat-U Icon carat-u
Check Icon check
Clock Icon clock
Cloud Icon cloud
Comment Icon comment
Delete Icon delete
Edit Icon edit
Eye Icon eye
Forbidden Icon forbidden
Forward Icon forward
Gear Icon gear
Grid Icon grid
Heart Icon heart
Home Icon home
Info Icon info
Location Icon location
Lock Icon lock
Mail Icon mail
Minus Icon minus
Navigation Icon navigation
Phone Icon phone
Plus Icon plus
Power Icon power
Recycle Icon recycle
Refresh Icon refresh
Search Icon search
Shop Icon shop
Star Icon star
Tag Icon tag
User Icon user
Video Icon video

jQuery Mobile uses SVG (Scalable Vector Graphics) to present icons for those browsers that support SVG and uses PNG images for those browsers that do not support SVG.

The stock icons are great - but often we'll wish to use different icons, either because none of the default icons fits our purpose, because we want a different creative look, or both. You can create your own icons by adding some custom CSS and referencing SVG and/or PNG versions of a small image.

We created a small (14px by 14px) image of a smiling face: Smiling Face The image we show here has a gray background for contrast; the real image - the one we use in our code - has a transparent background behind the white eyes and smile.

Let's use our new icon - open up ThemeFramework/Demos/icons/index.html to check out the code:

Baby Icon

Code Sample:


Code Explanation:

We add the class ui-icon-smile to the link button - where smile is a name we made up to reference our custom icon - in the main body content, along with classes to make the link a button and position the icon.

We then add some CSS to handle this button. The rule for .ui-icon-smile:after tells jQuery Mobile to use our icon whenever a "smile" icon is called for. We could have (but don't here) included an SVG version of the icon, too.

Custom CSS

As jQuery Mobile is an HTML5 framework, there's nothing to stop us from adding our own custom CSS rules to pages to add any visual style we want. We can style text, images, widgets, form controls, or other elements by hand, just as we would any desktop site. Of course, working with the framework - default themes and icons and ThemeRoller custom themes - will be easier than hand-crafting CSS for every creative aspect of our sites. But achieving that stunning, unique look for your site probably means a bit of custom CSS. We'll look at some examples in this next exercise.

Updating the Nan & Bob Site's Look

Let's give some sample pages from the Nan & Bob's site a facelift using ThemeRoller, custom icons, and some manual updates to the site's style. Nan & Bob want to adopt a green-based look for their site and also to incorporate a new logo into the site. We'll start with a ThemeRoller theme:

ThemeRoller green theme

We'll use this theme as a starting point, add the Nan & Bob's logo image, and use some custom icons to style the home page (on the left, in the screenshot below) and interior pages (on the right) like this:

theme exercise

Styling the Nan & Bob's Site

Duration: 25 to 35 minutes.

In this exercise, you will style the Nan & Bob's site with a custom theme, a large home page logo image, and custom icons.

  1. Open ThemeFramework/Exercises/newdesign/index.html in a file editor.
  2. Create a custom theme in ThemeRoller - you can make it heavy on the green, or choose your own colors.
  3. Download and save your custom theme; save the unpacked downloaded files to ThemeFramework/Exercises/newdesign/themes.
  4. Link to the downloaded minified stylesheet in the head of index.html where indicated. Also link to the "structure" CSS from jQuery Mobile.
  5. Add a two-column grid in the content div of the #home page, with the logo (from the images directory) on the left and the indicated text on the right. Add a CSS rule to make the right-side text large.
  6. We've included some images for the various icons, or feel free to create or find your own; they should be 14px by 14px. Set each of the home page listview links to display the custom icons, and add a navbar element to the header of each of the interior pages, with the appropriate custom icons.
  7. Add CSS rules to display each of the custom icons from their data-icon attributes.
  8. Add a background image to the entire site - we've included images/bg.png, or feel free to find your own; apply the background image to elements of class ui-page.
  9. Try out any other custom-CSS changes to change the visual appearance of the site.
  10. Test your work in a mobile browser.



Code Explanation:

We add a style link in head of the .html file to add the custom-theme stylesheet we downloaded from ThemeRoller; as before, we also link the CDN-hosted jquery.mobile.structure-1.1.0.min.css stylesheet to bring in the structural jQuery Mobile CSS.

We add a div with class ui-grid-a to display a two-column grid, with the logo on the left and text on the right; some custom CSS displays the content appropriately.

We added a gradient background color for the main element on the homepage.

We use the data-icon to customize the icons for the home page listview and the interior page navbars, with some custom CSS to display the correct icons.

Last, we add the background image to class ui-page, with the image repeating.