Get an introduction to the jQuery Mobile framework. Learn the basics of the framework and how to write a functional mobile web application user interface. In this article, an example guides you through basic pages, navigation, toolbars, list views, form controls, and transition effects.


C. Enrique Ortiz, Developer and author, Freelance

C. Enrique Ortiz is a long-time mobile technologist and author. A former space shuttle software engineer who decided to focus on mobile technologies rather than working on dangerous rockets, he advises developers, start-up companies, and investors on all things mobile: technology, strategy, products, and go-to-market.

29 May 2012

Also available in Russian Japanese Portuguese Spanish


jQuery Mobile is a superb framework for writing mobile web applications. Built on top of the popular jQuery and jQuery user interface (UI), jQuery Mobile is an effective, unified framework for writing your mobile web application. With jQuery Mobile you can ensure consistent look, feel, and behavior across different mobile platforms. The basic features of jQuery Mobile include:

  • General simplicity and flexibility
    The framework is simple to use. You can:
    • Develop pages primarily using markup driven with minimal or no JavaScript.
    • Use advanced JavaScript and events.
    • Use a single HTML document with multiple embedded pages.
    • Break your application into multiple pages.
  • Progressive enhancement and graceful degradation
    While jQuery Mobile leverages the latest HTML5, CSS 3, and JavaScript, not all mobile devices provide such support. jQuery Mobile philosophy is to support both high-end and less capable devices, such as those without JavaScript support, and still provide the best possible experience.
  • Support for touch and other input methods
    jQuery Mobile provides support for different input methods and events: touch, mouse, and cursor focus-based user input methods.
  • Accessibility
    jQuery Mobile is designed with accessibility in mind. It has support for Accessible Rich Internet Applications (WAI-ARIA) to help make web pages accessible for visitors with disabilities using assistive technologies.
  • Lightweight and modular
    The framework is lightweight with an overall size (minified and gzipped for Version 1.0.1) of 24KB for the JavaScript library, 7KB for the CSS, plus some icons.
  • Theming
    The framework also provides a theme system that allows you to define your own application styling. With the new ThemeRoller application you can easily create your own themes.

The jQuery Mobile framework includes all the UI components needed for building complete mobile web applications and websites: pages, dialogs, toolbars, different kinds of list views, a variety of form elements and buttons, and more. jQuery Mobile is built on top of jQuery core, so you have access to key facilities, including: HTML and XML document object model (DOM) traversing and manipulation; event handling; server communication using Ajax; and animation and image effects for web pages.

With jQuery Mobile, you can write basic mobile web applications without much effort. Because jQuery Mobile is a very comprehensive framework with advanced events and APIs, you can also write advanced mobile web applications and websites.

This article introduces the basics in the latest version of jQuery Mobile (Version 1.0.1). Learn about browser support, the UI components, and the API. To follow along with this article, you will need:

  • Previous exposure to HTML
  • An understanding of JavaScript fundamentals
  • Basic knowledge of jQuery

You can download the jQuery Mobile source code example used with this article. The Resources section has information about jQuery Mobile, jQuery, JavaScript, DOM, HTML5, and more.

Browser support

Mobile browsers have come a long way, but not all mobile devices provide support for HTML5, CSS 3, and JavaScript. This arena is where jQuery Mobile's progressive enhancement and graceful degradation support come into play.

jQuery Mobile supports both high-end and less capable devices, such as those without JavaScript support. Progressive enhancement, which is a design philosophy, consists of the following core principles (Wikipedia):

  • All basic content should be accessible to all browsers.
  • All basic functionality should be accessible to all browsers.
  • Enhanced layout is provided by externally linked CSS.
  • Enhanced behavior is provided by externally linked JavaScript.
  • End user browser preferences are respected.

All basic content should render (as designed) on basic devices, while more advanced platforms and browsers will be progressively enhanced with additional, externally linked JavaScript and CSS.

jQuery Mobile provides support for a large number of mobile devices. jQuery Mobile classifies, or groups, device support into three categories based on their level of support:

  • A-grade: Devices with support for a fully enhanced experience with Ajax-based animated page transitions. jQuery Mobile supports over 20 different devices, including: iOS 3.2-5.0; Android 2.1-2.3 and 3.0; BlackBerry 6-7 and Playbook; Skyfire 4.1; Opera Mobile; and the desktop browsers Chrome, Firefox, Internet Explorer, and Opera.
  • B-grade: Devices with support for an enhanced experience but without Ajax navigation features. Supported devices include: BlackBerry 5.0, Opera Mini 5.0-6.5, and Nokia Symbian ^3.
  • C-grade: Devices with support for a basic, non-enhanced HTML experience. Supported devices include: older smartphones, including BlackBerry 4.x, Windows Mobile, and others.

See Resources for a complete list of jQuery Mobile supported platforms.

The rest of this article discusses the jQuery Mobile page structure, HTML5 data attributes, and UI components.

Structure of a jQuery Mobile page

As shown in Listing 1, a typical jQuery Mobile page has three sections: a header, content, and footer section.

Listing 1. Typical jQuery Mobile page
lt;div data-role="page" id="page1">
    <div data-role="header">
    <div data-role="content">
    <div data-role="footer">

Figure 1 shows the structure from Listing 1.

Figure 1. Structure of an HTML5 jQuery Mobile page
Image with a header, a content area, and a footer

The header section is where you would typically place the page headers and things like logos. The content section is where the web application-specific content and the various widgets go. The footer section is great for navigation purposes.

To take advantage of jQuery Mobile advanced features and HTML syntax, a jQuery Mobile HTML document must define the HTML5 doctype. The rest of the HTML document consists of the:

  • <head> and <body> sections, where <head> contains the references to jQuery Mobile and the CSS mobile themes
  • <body> section that contains the actual jQuery Mobile content

Listing 2 shows an example of an HTML5 jQuery Mobile document.

Listing 2. jQuery Mobile HTML5 page structure
//Define the HTML5 doctype:

<!DOCTYPE html> 

// Define the HTML5 <head> with references to jQuery, jQuery Mobile and CSS mobile themes:


    <title>Page Title</title> 
    <meta name="viewport" content="width=device-width, initial-scale=1"> 

    <link rel="stylesheet" href="" />
    <script src="//"></script>
    <script src="//

// Define the HTML document <body> that includes the jQuery Mobile elements:


<div data-role="page" id="page1">

    <div data-role="header">

    <div data-role="content">


    <div data-role="footer">

<div data-role="page" id="page2">


// The footer can be turned into a navigation bar very easily, as follows:

<div data-role="footer" class="ui-bar">
<div data-role="controlgroup" data-type="horizontal">
<a href="index.html" data-role="button">One</a>
<a href="index.html" data-role="button">Two</a>
<a href="index.html" data-role="button">Three</a>
<a href="index.html" data-role="button">None</a>

Figure 2 shows the page footer created in Listing 2.

Figure 2. Page footer
Image of page footer with buttons 'One,' 'Two,' 'Three,' and 'None'

Though the page, header, content, and footer attributes are optional, it is recommended that you use them; they make the pages clearer to follow with respect to jQuery Mobile.

Single pages, multiple pages, and page linking

A single HTML document can have one or multiple jQuery Mobile pages, as indicated by the data-role="page" attribute. If you have multiple pages, you must specify the id attribute with a unique page ID that is used for linking between internal pages. When loading a multi-page HTML document, only the first page is shown.

jQuery Mobile uses Ajax for page loading, during which it shows the load spinner. If loading is successful, the UI widgets are enhanced, the page is added to the DOM, and page animation or transition is applied.

Linking and loading without Ajax forces the load to use HTTP. You will not get the animated transitions using this approach. Use rel="external", data-ajax="false", or target on the link to load without Ajax.

Supported events and methods

In JavaScript, when using jQuery you can refer to the jQuery object itself as $ and gain access to jQuery facilities. The jQuery Mobile framework, which extends jQuery core, is available using $.mobile, which also provides access to the jQuery Mobile-specific events and methods. Some of the events and methods exposed with $.mobile are described below.


As with other jQuery events, you bind to jQuery Mobile events by using the live() and bind() functions. For example, touch events include tap, taphold, and various swipe and virtual mouse events. You can bind to orientation changes and scroll events such as scrollstart and scrollstop. Page events allow you to receive notifications:

  • Prior to a page creation
  • When a page is created
  • Just before the page is shown or hidden
  • When the page is shown and hidden

Initializing jQuery Mobile

If you're familiar with jQuery, you might recall that to execute your code as soon as the DOM is loaded you need to initialize inside the $(document).ready() function. With jQuery Mobile, for initialization you bind to the pageinit event, as shown in Listing 3.

Listing 3. Binding to the pageint event
$( '#welcomePage' ).live( 'pageinit',function(event){

The pageinit event is triggered for the referenced page after page initialization occurs. It will work regardless of how the page is loaded (directly or with Ajax).

Overriding jQuery Mobile defaults

If you bind to the mobileinit event, which is triggered when jQuery Mobile starts to execute, you can override some of jQuery Mobile's default values. Listing 4 shows an example. You can override the default page transition, the default page loading text, the default page loading theme, and many others.

Listing 4. Initializing jQuery Mobile
$(document).bind("mobileinit", function(){
  //apply overrides here

Learn more about jQuery default values by visiting the jQuery Mobile global configuration page (see Resources).


jQuery Mobile also provides a number of methods with the $.mobile object. Table 1 shows some of the available methods.

Table 1. jQuery Mobile methods
$.mobile.changePageTo programmatically change from one page to another. For example, to go to page weblog.php using a slide transition, use $.mobile.changePage("weblog.php", "slide").
$.mobile.loadPageTo load an external page, enhance it with jQuery Mobile, and insert it into the DOM.
$.mobile.showPageLoadingMsgTo show the page loading message.
$.mobile.hidePageLoadingMsgTo hide the page loading message.
$.mobile.path.isSameDomainA utility method to compare the domain of two URLs.
$.mobile.activePageA reference to the page that is currently in view.

The jQuery Mobile methods page has more methods and utilities (see Resources).

Widgets and HTML5 data-* attributes

jQuery Mobile relies on HTML5 data-* attributes to support the various UI elements, transitions, and page structure. These HTML5 attributes are the key to jQuery Mobile's simplicity. Browsers that don't support HTML5 will silently discard the HTML5 attributes.

The following list shows the code and renderings of different UI widgets and data-* attributes and how to use them to create UI components.

  • Page, header, content, and footer
    Listing 5. Page, header, content, and footer
    <div data-role="page" id="page1">
        <div data-role="header">
        <div data-role="content">
           CONTENT AREA
        <div data-role="footer">
    Figure 3. Page, header, content, and footer
    Page, Header, Content, and Footer
  • Basic button
    Listing 6. Basic button
    <a href="index.html" data-role="button" data-icon="info">Button</a>

    Figure 4. Basic button
    Basic button
  • Checkbox
    Listing 7. Checkbox
    <input type="checkbox" name="checkbox-1" id="checkbox-0" class="custom" />
    <label for="checkbox-0">Checkbox</label>
    Figure 5. Checkbox
  • Collapsible
    Listing 8. Collapsible
    <div data-role="collapsible">
    Figure 6. Collapsible
  • Open a dialog with transition
    Listing 9. Open a dialog
    <a href="dialog.html" data-rel="dialog" data-transition="pop">Open dialog</a>

    The code in Listing 9 is a hyperlink that will open a dialog widget with a transition of type "pop." Figure 7 illustrates an example of a dialog widget.

    Figure 7. Open a dialog
    open a dialog
  • Flip toggle switch
    Listing 10. Flip toggle switch
    <label for="flip-a">Select slider:</label>
    <select name="slider" id="flip-a" data-role="slider">
        <option value="off">Off</option>
        <option value="on">On</option>
    Figure 8. Flip toggle switch
    flip toggle switch
  • List view
    Listing 11. List view
    <ul data-role="listview" data-theme="g">
      <li><a href="Friends.html">Friends</a></li>
      <li><a href="SendMessage.html">Send Message</a></li>
      <li><a href="Share.html">Share</a></li>
    Figure 9. List view
    list view
  • Nav bar
    Listing 12. Nav bar
    <div data-role="navbar">
           <li><a href="a.html" class="ui-btn-active">One</a></li>
           <li><a href="b.html">Two</a></li>
    Figure 10. Nav bar
    Nav bar
  • Radio button
    Listing 13. Radio button
    <fieldset data-role="controlgroup">
        <legend>Choose a pet:</legend>
            <input type="radio" name="radio-choice-1" id="radio-choice-1" 
    value="choice-1" checked="checked" />
            <label for="radio-choice-1">Cat</label>
            <input type="radio" name="radio-choice-1" id="radio-choice-2" 
    value="choice-2"  />
            <label for="radio-choice-2">Dog</label>
            <input type="radio" name="radio-choice-1" id="radio-choice-3"
    value="choice-3"  />
            <label for="radio-choice-3">Hamster</label>
    Figure 11. Radio button
    radio button
  • Select (form)
    Listing 14. Select (form)
    <label for="select-choice-0" class="select">Shipping 
    <select name="select-choice-0" id="select-choice-1">
       <option value="standard">Standard: 7 day</option>
       <option value="rush">Rush: 3 days</option>
       <option value="express">Express: next day</option>
       <option value="overnight">Overnight</option>
    Figure 12. Select (form)
    Select (form)
  • Slider
    Listing 15. Slider
    <label for="slider-0">Input slider:</label>
    <input type="range" name="slider" id="slider-0" value="60" 
    min="0" max="100" />
    Figure 13. Slider
  • Text input
    Listing 16. Text input
    <label for="basic">Text Input:</label>
    <input type="text" name="name" id="basic" value=""  />
    Figure 14. Text input
    text input
  • Text area
    Listing 17. Text area
    <label for="textarea-a">Textarea:</label>
    <textarea name="textarea" id="textarea-a">
    Basic textarea.
    Figure 15. Text area
    text area
  • Grid
    Listing 18. Grid
    <div class="ui-block-a">Block A</div>
    <div class="ui-block-b">Block B</div>
    <div class="ui-block-c">Block C</div>


    • For two-column use the ui-grid-a class
    • For three-column use the ui-grid-b class
    • For four-column use the ui-grid-c class
    • For five-column use the ui-grid-d class
    Figure 16. Grid

The data-role attribute is used to define the different widgets. Not all of the UI widgets are driven by the data-role attribute, though (select, slider, and text input, for example). See the data- attribute reference for more detailed information about the different data-* attributes (see Resources).

As mentioned, the jQuery Mobile UI framework includes all the UI components needed for building complete mobile web applications and websites including pages, dialogs, toolbars, different kinds of list views, a variety of form elements, buttons, and others. We've covered the HTML5 data-* attributes used to define the different jQuery Mobile UI widgets. The rest of this section discusses the most common jQuery Mobile UI widgets.


Modal dialogs are an essential type of page that can be very useful for alerts or messages to the user. Any page can be turned into a modal dialog by adding the data-rel="dialog" attribute to the page's anchor link, as follows.

<a href="tc.html" data-rel="dialog" data-transition="pop">Terms of 

You can apply transitions and themes to the dialogs. The jQuery Mobile Dialog page has more information for reference (see Resources).

List views

List views are one of the most important UI elements for mobile applications. jQuery Mobile provides support for a rich set of list view elements, including basic, nested, split button, numbered, numbered bubble, and icon lists. Let's take a look at the code and renderings of some list views.

  • Basic-linked list
    Listing 19. Basic-linked list
    <ul data-role="listview">
      <li><a href="index.html">Acura</a></li>
    Figure 17. Basic-linked list
    basic linked list
  • Nested list
    Listing 20. Nested list
    <ul data-role="listview">
        <p>All your favorites from aarkvarks to zebras.</p>
                <li><a href="index.html">Canary</a></li>
                <li><a href="index.html">Cat</a></li>
                <li><a href="index.html">Dog</a></li>
                <li><a href="index.html">Gerbil</a></li>
                <li><a href="index.html">Iguana</a></li>
                <li><a href="index.html">Mouse</a></li>
    Figure 18. Nested list
    nested list
  • Numbered list
    Listing 21. Numbered list
    <ol data-role="listview">
      <li><a href="index.html">The Godfather</a></li>
    Figure 19. Numbered list
    numbered list
  • Split button list
    Listing 22. Split button list
    <ul data-role="listview" data-split-icon="gear" data-split-theme="d">
        <a href="index.html">
        <img src="images/album-ws.jpg" />
        <p>The White Stripes</p>
        </a><a href="lists-split-purchase.html" data-rel="dialog" 
    data-transition="slideup">Purchase album</a>
    Figure 20. Split button list
    split button list

Inset-style lists

jQuery Mobile supports all of its list views as inset-style lists (lists with rounded corners) by specifying the data-insert attribute, as shown in Figure 21.

Figure 21. Inset-style list
inset-style list

Listing 23 shows the code an inset-style list.

Listing 23. Inset-style lists
<ul data-role="listview" data-inset="true">
      <a href="index.html">Get Friends</a>
      <a href="index.html">Post to Wall</a>
      <a href="index.html">Send Message</a>

jQuery Mobile provides a rich set of list views. For more information, see the jQuery Mobile list view page (see Resources).


Forms are a common web artifact for posting information to a server. jQuery Mobile supports many form UI components: text inputs, search inputs, slider, flip toggle switch, radio buttons, check boxes, select menus, and theming forms. They can all be created easily. The previous section covered the majority of these elements.

jQuery Mobile provides a rich set of form elements. Listing 24 shows a form with a select menu and a submit button.

Listing 24. Simple form and submit button
<form action="forms-results.php" method="get"> 
        <div data-role="fieldcontain">
            <label for="select-options" class="select">Choose 
an option:</label>
            <select name="select-options" id="select-options">
                <option value="option1">Option 1</option>
                <option value="option2">Option 2</option>
                <option value="option2">Option 3</option>
        <button type="submit">Submit</button> 

Select menus are driven by native <select name="select-options" id="select-options">, but jQuery Mobile improves on its "look and feel." The <div data-role="fieldcontain"> statement groups the different values for visualization purposes. The form itself is defined by native <form action="..." method="get">.

Figure 22 shows the result from Listing 24.

Figure 22. Simple form with selection menu and submit button
simple form with selection menu and submit button

The jQuery Mobile form elements page has more information (see Resources).

Page transitions

jQuery Mobile supports a number of cool CSS-based transitions, listed in Table 2, that can be applied to both dialogs and pages.

Table 2. CSS-based transitions
fadeFade in/fade out transition effect
popPop transition effect
flipFlip transition effect
turnTurn transition effect
flowFlow (similar to slide) transition effect
slideThe (horizontal) slide transition effect
slideupShow page or dialog sliding from the bottom to the top of the page
slidedownShow page or dialog sliding from the top to the bottom of the page
noneNo transition effect

To force a specific animation, add the data-transition attribute on the link, as shown in Listing 25.

Listing 25. Add data-transition attribute
<a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog"

Transitions are hardware accelerated and require 3D transform support by the browser. Devices that don't provide 3D support will fall back to fade.

The jQuery Mobile transitions page shows the transitions in action and other related information (see Resources).

Themes and ThemeRoller

With jQuery Mobile, you can use the data-theme attribute to customize the look of your application with themes. jQuery Mobile provides one default theme and five additional swatches, named A through E, as shown in Table 3.

Table 3. Themes and styles
Default themeDefault them
Swatch ADefault them
Swatch BDefault them
Swatch CDefault them
Swatch DDefault them
Swatch EDefault them

You can theme individual elements, such as a page, a button, and so on.

With the ThemeRoller web-based application, shown in Figure 23, you can create themes for your mobile web application or mini website. You can also use ThemeRoller to build your own theme, download the custom CSS file, and use it on your project.

Figure 23. ThemeRoller
theme roller


In this article, you have learned some of the basics of the jQuery Mobile framework. Examples in this article showed how to use basic pages, navigation, toolbars, list views, form controls, and transition effect. The framework offers much more, including other methods and events for advanced applications. With jQuery Mobile you can also use and customize widgets. Hopefully you're now inspired to write functional mobile web application UIs using jQuery Mobile.


jQuery plugin source codejquerymobileexamplecode.zip2KB



Get products and technologies



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 Web development on developerWorks

Zone=Web development, Mobile development, Open source
ArticleTitle=Introduction to jQuery Mobile