Create custom jQuery mobile themes

Customize the look of pages, toolbars, content, form elements, lists, buttons, and more

The high adoption rate of smartphones and tablet devices is ultimately increasing the demand for mobile web developers and designers. The jQuery Mobile framework lets you create mobile web experiences that rival the results of native application development by providing instant access to applications and websites via the web browser rather than making users download and install mobile applications. Learn how to use the jQuery Mobile theming framework to create custom-branded mobile websites and web applications.


Kris Hadlock, Web Developer/Designer, Studio Sedition

Photo of Kris HadlockKris Hadlock has been a contract web developer and designer since 1996. He has worked on projects for companies such as SPIN Magazine, IKEA, United Airlines, JP Morgan Chase, GoDaddy Software, and Fire Mountain Gems. He is the author of Ajax for Web Application Developers (Sams) and The ActionScript Migration Guide (New Riders) as well as a featured columnist and writer for numerous websites and design magazines, including,, and Practical Web Design magazine. Kris is also the founder of, a web design and software development studio specializing in fusion of form and function.

15 November 2011

Also available in Chinese Vietnamese Portuguese Spanish

The jQuery Mobile framework is a JavaScript library that you can use to easily create a mobile version of a website, converting existing web pages into touch-friendly websites and applications. The jQuery Mobile framework affects the way mobile applications are accessed and distributed on mobile and tablet devices by allowing users to connect directly to touch-friendly applications through a web browser.

Mobile and tablet device adoption rates are skyrocketing, and the jQuery Mobile framework is allowing developers to meet the growing demand for these mobile web experiences by increasing the speed with which mobile web sites can be produced.

In particular, jQuery Mobile includes a theme framework that you can easily customize. The ability to customize color swatches and icon sets provides custom theming of pages, toolbars, content, form elements, lists, buttons, and more. This article provides a brief overview of how to create a custom theme for each of these jQuery Mobile element types. Custom theming allows you to create mobile versions of websites that follow the same branding as their desktop versions.

Theming jQuery Mobile

Jammed-up back-end backlog?

Sign up for a free Bluemix cloud trial and fork this sample code to quickly add authentication, push notifications, and persistent mobile data to your app.

Now you can focus on the part of the app your parents actually understand. Learn more.

jQuery Mobile has a recommended but optional page structure for standard web applications that includes a few common constructs, such as a page element that contains header, content, and footer elements. To define these elements, the jQuery Mobile framework uses the HTML5 data-role attribute. Listing 1 shows an example of jQuery Mobile's recommended HTML template using data-role for each main element.

Listing 1. An element using the page data-role
<div data-role="page">

	<div data-role="header">
		<h1>Page Title</h1>

	<div data-role="content">
		<p>Page content goes here.</p>		

	<div data-role="footer">
		<h4>Page Footer</h4>

Another important and recommended element is a <meta viewport> tag. This tag specifies how a browser should display the mobile website. The following code shows how to add a <meta> tag to set the viewport for mobile devices:

<meta name="viewport" content="width=device-width, initial-scale=1">

The <meta viewport> tag is important for rendering your mobile web page properly based on the device accessing it. Without this tag, your web page can appear small, or zoomed out, as any normal web page not built for mobile would display. Figure 1 shows a mobile web page that uses the <meta viewport> tag and displays the content more appropriately for the device being used.

Figure 1. A mobile web page using the <meta viewport> tag
A mobile web page using the <meta viewport> tag

The jQuery Mobile framework includes a page theming system that provides full control over the look and style of page elements. The HTML5 data-theme attribute can be added to an element to apply an existing jQuery Mobile theme color swatch or a new color swatch. The theming system includes five swatches, using a letter to identify each one—for example, A-E are the swatches the jQuery Mobile framework provides natively. You can view the existing swatches by downloading the CSS file that the jQuery Mobile framework provides. To create a new swatch, you can use any letter of the alphabet not already being used (namely, F-Z). Once you determine the letter you'd like to use, you can reference any of the existing swatches to copy and customize classes for all of the various page elements.

Page theming

Page theming consists of styling the HTML element that contains the entire web page. jQuery Mobile's recommended page structure consists of a <div> element that includes a data-role attribute with a value for page. To style this element, apply a data-theme attribute to it and specify a unique and unused value for a new swatch so that you can write a custom CSS for it. The following code shows an example of the page element using a data-theme value of F:

<div data-role="page" data-theme="f">

By using this data-role and data-theme, the jQuery Mobile framework actually creates and adds a few CSS classes to the page element. Here's an example of what the output in the browser becomes after being processed by the framework:

<div data-role="page" data-theme="f" 
class="ui-page ui-body-f ui-page-active" style="min-height: 580px;">

As you can see, a number of CSS classes have been added to the page element. The ui-page and ui-page-active classes have been assigned based on the data-role value of page, and the ui-body-f class has been assigned based on the data-theme value of F. You can use any of these classes to style the page element or its contents. Listing 2 shows an example of how to use the ui-body-f class to add custom styling to the page element.

Listing 2. Styling the jQuery Mobile page element using CSS
.ui-body-f {
  background-color: #f9f9f9;
  font-family: "Lucida Sans Unicode", "Lucida Grande", Arial, sans-serif;

The custom CSS you've added to this class sets the background color and font used in the mobile web page. Once you have created your page swatch, you can get more specific with the HTML elements you want to target and stylize. For example, Listing 3 shows how to target and stylize input text and password fields that appear within the page element.

Listing 3. Stylizing all input text and password fields that appear within the page element
.ui-body-f input[type="text"], 
.ui-body-f input[type="password"] {
  background-color: #ccc;

The possibilities are endless once you have gained control over the page element. With this containing element of the web page contents, you can truly target and customize any element.

Toolbar theming

In the jQuery Mobile framework, toolbars are header and footer elements. To define a toolbar as a header or footer, you use the data-role attribute. The value of the data-role attribute should be header or footer depending on the element you are creating. Listing 4 provides an example of both header and footer toolbars included within a page element.

Listing 4. Using header and footer toolbars
<div data-role="header">
	<h1>Page Title</h1>

<div data-role="footer">
	<h4>Page Footer</h4>

Assigning a theme to a toolbar is as easy as using the data-theme attribute and giving it a custom swatch value. By default, header and footer toolbars are assigned the a color swatch to show visual hierarchy. Here's an example of a custom theme assigned to the header toolbar:

<div data-role="header" data-theme="f">
	<h1>Page Title</h1>

To stylize this theme, you need to create a new CSS class for the bar (Listing 5).

Listing 5. Styling the header toolbar
.ui-bar-f {
  padding: 10px 0px;
  background-color: #069;
  border-bottom: 2px solid #036;
  color: #fff;

This new custom CSS class stylizes all the toolbars that have the F data-theme applied. However, there are often times when you'd like your header and footer to look different. To achieve this difference, you need to create a new custom theme—name it G—and create a new CSS class to style it (Listing 6).

Listing 6. Adding a custom CSS class for the footer toolbar
.ui-bar-g {
  margin-top: 20px;
  padding: 10px 0;
  color: #fff;
  border-bottom: 2px solid #000;

  background-color: #000;
  background: -moz-linear-gradient(top, rgba(204,204,204,1) 0%, rgba(0,0,0,0.65) 100%); 
  /* FF3.6+ */
  background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,
  rgba(204,204,204,1)), color-stop(100%,rgba(0,0,0,0.65))); /* Chrome,Safari4+ */
  background: -webkit-linear-gradient(top, rgba(204,204,204,1) 0%,
  rgba(0,0,0,0.65) 100%); /* Chrome10+,Safari5.1+ */
  background: -o-linear-gradient(top, rgba(204,204,204,1) 0%,rgba(0,0,0,0.65) 100%); 
  /* Opera11.10+ */
  background: -ms-linear-gradient(top, rgba(204,204,204,1) 0%,rgba(0,0,0,0.65) 100%); 
  /* IE10+ */
  filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#cccccc', 
  endColorstr='#a6000000',GradientType=0 ); /* IE6-9 */
  background: linear-gradient(top, rgba(204,204,204,1) 0%,rgba(0,0,0,0.65) 100%); 
  /* W3C */

The G toolbar theme sets some basic properties, but it also includes complex multiple gradients for different browsers. These gradients are intimidating, but luckily you don't need to memorize how to create them, as there are websites that will generate them for you. So, you can simply copy and paste the code into your CSS class. Visit the Resources section of this article for a link to generate gradients for your website.

Content theming

The content element can be themed to the custom swatch of your choice. To create a custom swatch for the content in your mobile website, you must first create a content element (Listing 7).

Listing 7. Adding a collapsible block to your content element
<div data-role="collapsible" data-collapsed="true" data-theme="f">
    Login form will go here

This block will collapse when the page is loaded. When a user clicks the title bar, it will reveal the login form that you will create shortly. To style this block, simply assign a data-theme to it and create a custom CSS class. Listing 8 provides an example of some custom classes associated with the collapsible block and its contents.

Listing 8. Custom CSS classes associated with the title bar for the collapsible block
ui-body-f .ui-collapsible-contain 
.ui-collapsible-heading .ui-btn-up-f {
  background: #666;
  color: #fff;
  text-decoration: none;
.ui-body-f .ui-collapsible-contain 
.ui-collapsible-heading .ui-btn-down-f, 
.ui-body-f .ui-collapsible-contain 
.ui-collapsible-heading .ui-btn-hover-f {
  background: #999;
  color: #fff;
  text-decoration: none;

These CSS classes define the non-active, active, and hover state of the collapsible title bar. The <h3> tag from Listing 7 is converted into an <h3> with a ui-collapsible-heading class; the contained text—in this case, "Login"—is converted into a hyperlink with a few classes, depending on the state. The three classes for the hyperlink are ui-btn-up-f, ui-btn-down-f, and ui-btn-hover-f. Each of these classes is self-explanatory, covering the up, down, and hover state of the title bar for the collapsible content block. The classes change depending on the data-theme value, so these classes include an appended F at the end; if you were to use a data-theme value of G, the classes would have a G appended to the end in place of the F.

List theming

Lists are common on mobile web pages, because they provide a way to quickly show options for people on the go. To convert a regular HTML list into a fancy mobile list that's easy to use on touch devices, all you need to do is set the data-role attribute to listview, as shown in Listing 9.

Listing 9. Converting a simple HTML list into a touch-friendly list
<ul data-role="listview" data-inset="true" data-theme="f">
  <li><a href="#">Title name</a></li>
  <li><a href="#">Title name</a></li>
  <li><a href="#">Title name</a></li>

By default, lists appear as the full width of the browser window, as Figure 2 shows.

Figure 2. The default appearance of a listview in jQuery Mobile
The default appearance of a listview in jQuery Mobile

However, if you want to inset the list items and round the corners, you can use the data-inset attribute and set its value to true, as shown in Figure 3.

Figure 3. A listview with the data-inset attribute set to true
A listview with the data-inset attribute set to true

Adding a theme to the listview is easy. As you've done with every other theme, simply assign a data-theme value. Listing 9 used F as the theme value. To customize the list items, you need to target them with CSS, as Listing 10 shows.

Listing 10. Customizing the list items
.ui-listview .ui-btn-up-f a, 
.ui-listview .ui-btn-down-f a, 
.ui-listview .ui-btn-hover-f a {
  color: #fff;

The elements you're targeting with the CSS in Listing 10 are the actual hyperlinks within the list items to set the text color to white. The ui-btn-up-f, ui-btn-down-f, and ui-btn-hover-f classes are all injected by jQuery Mobile to handle the different states of the list items.

Form and button theming

You create a form for a mobile website using the jQuery Mobile framework the same way you would for any website: Simply add input elements and associated labels, which will take on the existing page theme. Listing 11 provides an example.

Listing 11. Creating a mobile form
<div data-role="collapsible" data-collapsed="true" data-theme="f">
  <form action="" method="post">
    <label for="username">Username</label>
    <input type="text" name="username" id="username" />
    <label for="username">Password</label>
    <input type="password" name="password" id="password" />
    <fieldset class="ui-grid-a">
      <div class="ui-block-a">
        <button type="reset" data-inline="true">Reset</button>
      <div class="ui-block-b">
        <button type="submit" data-inline="true" data-theme="f">Submit</button>

Form elements can also be custom themed. Listing 12 shows an example of how a form is stylized using the F theme from your page element.

Listing 12. Custom styling for the input elements used in your login form
.ui-body-f input[type="text"], 
.ui-body-f input[type="password"] {
  background-color: #ccc;

In Listing 11, you probably noticed the fieldset with custom button code. Each button has a different theme associated with it: The Reset button uses the default theme, while the Submit button uses the F theme. Listing 13 shows the custom CSS classes created for these two buttons to make them different in appearance.

Listing 13. Custom CSS classes for form buttons
.ui-btn-up-f {
  background: -moz-linear-gradient(top, rgba(57,107,158,1) 0%, 
  rgba(78,137,197,0.65) 100%); /* FF3.6+ */
  background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,
  rgba(57,107,158,1)), color-stop(100%,rgba(78,137,197,0.65))); /* Chrome,Safari4+ */
  background: -webkit-linear-gradient(top, rgba(57,107,158,1) 0%,
  rgba(78,137,197,0.65) 100%); /* Chrome10+,Safari5.1+ */
  background: -o-linear-gradient(top, rgba(57,107,158,1) 0%,
  rgba(78,137,197,0.65) 100%); /* Opera11.10+ */
  background: -ms-linear-gradient(top, rgba(57,107,158,1) 0%,
  rgba(78,137,197,0.65) 100%); /* IE10+ */
  filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#396b9e', 
  endColorstr='#a64e89c5',GradientType=0 ); /* IE6-9 */
  background: linear-gradient(top, rgba(57,107,158,1) 0%,
  rgba(78,137,197,0.65) 100%); /* W3C */
  border: 1px solid #225377;
  text-shadow: #225377 0px -1px 1px;
  color: #fff;
.ui-btn-hover-f {
  background: -moz-linear-gradient(top, rgba(114,176,212,1) 0%, 
  rgba(75,136,182,0.65) 100%); /* FF3.6+ */
  background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,
  rgba(114,176,212,1)), color-stop(100%,rgba(75,136,182,0.65))); /* Chrome,Safari4+ */
  background: -webkit-linear-gradient(top, rgba(114,176,212,1) 0%,
  rgba(75,136,182,0.65) 100%); /* Chrome10+,Safari5.1+ */
  background: -o-linear-gradient(top, rgba(114,176,212,1) 0%,rgba(75,136,182,0.65) 100%); 
  /* Opera11.10+ */
  background: -ms-linear-gradient(top, rgba(114,176,212,1) 0%,
  rgba(75,136,182,0.65) 100%); /* IE10+ */
  filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#72b0d4', 
  endColorstr='#a64b88b6',GradientType=0 ); /* IE6-9 */
  background: linear-gradient(top, rgba(114,176,212,1) 0%,rgba(75,136,182,0.65) 100%); 
  /* W3C */
  border: 1px solid #00516E;
  text-shadow: #014D68 0px -1px 1px;
  color: #fff;

As you can see, the Save button has a custom gradient associated with it that makes it stand out more than the Reset button. Using multiple themes for button sets is a good way to identify which button is the most important or the primary button.


Theming a touch-friendly website with the jQuery Mobile framework is easy once you understand the data-theme attribute and the elements the framework provides. With the addition of the data-theme attribute, you can assign custom values and associated custom CSS classes that will allow you to create touch-friendly websites using the jQuery Mobile framework. To learn more about the framework, see the Resources section or, better yet, test out some custom CSS yourself using the sample code the Download section.


Sample jQuery Mobile webpagejquery-mobile-custom-themes.zip4KB



Get products and technologies

  • Download jQuery Mobile from the jQuery Mobile framework site.
  • IBM WebSphere Application Server Feature Pack for Web 2.0 and Mobile includes the IBM Dojo 1.7 Toolkit, new mobile and rich Internet application (RIA) building blocks, and a Dojo-based diagram component. With accompanying Rational tools, the Feature Pack helps you take WebSphere applications developed originally for desktop browsers and adapt and deploy them to mobile devices.
  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online or use a product in a cloud environment.


  • Get involved in the developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Mobile development on developerWorks

Zone=Mobile development, Web development, Open source
ArticleTitle=Create custom jQuery mobile themes