Syntax
Example
Explanation
- HTML
- Files to Include in Head Section
jquery.mobile-1.0b1.min.css
jquery-1.6.1.min.js
jquery.mobile-1.0b1.min.js
<head>
<title>Page Title</title>
<link rel="stylesheet"
href="http://code.jquery.com/mobile/1.0b1/jquery.mobile-1.0b1.min.css"/>
<script
type="text/javascript"
src="http://code.jquery.com/jquery-1.6.1.min.js"></script>
<script
type="text/javascript"
src="http://code.jquery.com/mobile/1.0b1/jquery.mobile-1.0b1.min.js"></script>
</head>
Docs&Demos
Include these lines in the <head> section of your document. The accepted practice is to reference the files on the public sites, not copy instances to your own site but you can do that.
- Page
- Construction
data-role="page"
data-role="header"
data-role="content"
data-role="footer"
data-role="button"
<div data-role="
page">
<div data-role="header">
<h1>Page Title</h1>
</div><!-- /header -->
<div data-role="content">
<p>Page content goes here.</p>
</div><!-- /content -->
<div data-role="footer">
<h4>Page Footer</h4>
</div><!-- /footer -->
</div><!-- /page -->
Docs&Demos
You can make individual HTML pages for your JQM pages but the idea for smaller mobile sites is to put some or all of your 'pages' in a single HTML file. JQM loads the subsection 'pages' with AJAX calls so there is less perceived server round trip. The default behavior is to display a "loading..." message.
Every page and subsection is a div. The purpose of divs is declared by the 'data-role' attribute.
- External References
rel="external"
<a href="index.html" rel="external"
Docs&Demos
Links that point to other domains or that have rel="external", data-ajax="false" or target attributes will not be loaded with Ajax and will cause a full page refresh. If multiple "pages" are contained within a single HTML document, they can be linked by referencing the ID of the page as an anchor (#foo).
- Transitions
data-transition="pop"
<a href="#mydialog" data-transition="pop">I'll pop</a>
data-transition="slide"
<a href="#mydialog" data-transition="slide">I'll slide</a>
data-transition="slideup"
<a href="#mydialog" data-transition="slideup">I'll slideup</a>
data-transition="slidedown"
<a href="#mydialog" data-transition="slidedown">I'll slidedown</a>
data-transition="fade"
<a href="#mydialog" data-transition="fade">I'll fade</a>
data-transition="flip"
<a href="#mydialog" data-transition="flip">I'll flip</a>
NOTE: The flip transition isn't rendered correctly on most versions of Android because it lacks 3D CSS transform capabilities. Unfortunately, instead of ignoring the flip, Android makes the page "cartwheel" away by rotating instead of flipping. We recommend using this transition sparingly until support improves.
data-direction="reverse"
<a href="index.html" data-transition="slide" data-direction="reverse">I'll pop</a>
Note: (this was formerly data-back="true", which will remain supported until 1.0)
- Dialogs
- Dialog Declaration
data-rel="dialog"
<a href="foo.html" data-rel="dialog">Open dialog</a>
- Forcing 'Back'
data-rel="back" See also Back Button
For JavaScript-generated links, you can simply set the href attribute to "#" and use the data-rel="back" attribute. You can also call the dialog's close() method to programmatically close dialogs, for example: $('.ui-dialog').dialog('close').
- Headers and Footers
- Position Inline
data-position="inline"
<div data-role="header" data-position="inline">
Docs&Demos
Header and footers can be positioned on the page in a few different ways. By default, the toolbars use the "inline" positioning mode. In this mode, the headers and footer sit in the natural document flow (the default HTML behavior), which ensures that they are visible on all devices, regardless of JavaScript and CSS positioning support.
- Fixed (Docked) Positioning
data-position="fixed"
<div data-role="header" data-position="fixed">
Docs&Demos
A "fixed" positioning mode provides the convenience of static toolbars without the drawbacks of implementing faux-scrolling in JavaScript. The toolbars start in their natural positions on the page, like the "inline" mode, but when a bar scrolls out of the viewport, the framework animates the bar back into view by dynamically re-positioning the bar to the top or bottom of the viewport.
- Fullscreen
data-position="fixed"
code
Docs&Demos
Fullscreen" position mode works just like the fixed mode except that the toolbars aren't shown at the top and bottom of the page and only appear when the page is clicked. This is useful for immersive apps like photo or video viewers where you want the content to full when whole screen and toolbars can be summoned to appear by tapping the screen. Keep in mind that the toolbars in this mode will sit over page content so this is best used for specific situations.
- Header Declaration
<div data-role="header">
<div data-role="header">
- Button Alignment
class="ui-btn-right"
class="ui-btn-left"
<a href="index.html" data-icon="gear"
class="ui-btn-right">Options</a>
<a href="index.html" data-icon="gear"
class="ui-btn-left">Edit</a>
The button position can also be controlled by adding classes to the button anchors, rather than relying on source order. This is especially useful if you only want a button in the right slot. To specify the button position, add the class of ui-btn-left or ui-btn-right to the anchor.
- Footer
- Footer Declaration
data-role="footer"
<div
data-role="footer" class="ui-bar">
explanation
- Padding
class="ui-bar"
<div data-role="footer" class="ui-bar">
Docs&Demos
By default, toolbars don't have any padding to accommodate nav bars and other widgets. To include padding on the bar, add a class="ui-bar" to the footer.
- Persistent Footer
data-id
data-id
In situations where the footer is a global navigation element, you may want it to appear fixed in place between page transitions. This can be accomplished by using the persistent footer feature included in jQuery Mobile.
To make a footer stay in place between transitions, add the data-id attribute to the footer of all relevant pages and use the same id value for each. For example, by adding data-id="myfooter" to the current page and the target page, the framework will keep the footer anchors in the same spot during the page animation. PLEASE NOTE: This effect will only work correctly if the header and footer toolbars are set to data-position="fixed" so they are in view during the transition.
- Back Button
- Presence of
data-add-back-btn="true"
data-add-back-btn="true"
jQuery Mobile has a feature to automatically create and append "back" buttons to any header, though it is disabled by default. This is primarily useful in chromeless installed applications, such as those running in a native app web view. The framework automatically generates a "back" button on a header when the page plugin's addBackBtn option is true. This can also be set via markup if the page div has a data-add-back-btn="true" attribute.
- Destination
data-rel="back"
data-rel="back"
Docs&Demos
If you use the attribute data-rel="back" on an anchor, any clicks on that anchor will mimic the back button, going back one history entry and ignoring the anchor's default href. This is particularly useful when linking back to a named page, such as a link that says "home", or when generating "back" buttons with JavaScript, such as a button to close a dialog. When using this feature in your source markup, be sure to provide a meaningful href that actually points to the URL of the referring page (this will allow the feature to work for users in C-Grade browsers. Also, pease keep in mind that if you just want a reverse transition without actually going back in history, you should use the data-direction="reverse" attribute instead.
- Back Text
data-back-btn-text="previous"
data-back-btn-text="previous"
- Other Buttons
- Button Declaration
data-role="button"
<a href="index.html" data-role="button">Link button</a>
Docs&Demos
For ease of styling, the framework automatically converts any button element or input with a type of submit, reset, button, or image into a custom styled link-based button — there is no need to add the data-role="button" attribute.
- Icon Image
data-icon="delete"
<a href="index.html" data-role="button" data-icon="delete">Delete</a>
alert
arrow-l
arrow-r
arrow-u
arrow-d
back
check
delete
forward
gear
grid
home
info
minus
plus
refresh
search
star
- Alignment
data-iconpos="right"
<a href="index.html" data-role="button" data-icon="delete" data-iconpos="right">Delete</a>
top, bottom
- Defeating/Removing Button Icon
data-icon="false"
<li class="section" data-theme="a" data-icon="false"><a href="#" >Page</a></li>
- Defeating Text
data-iconpos="notext"
<a
href="index.html"
data-role="button"
data-icon="delete"
data-iconpos="notext"
>Delete</a>
- Custom Icons
data-icon="<my icon name>"
CSS:
.ui-icon-<data-icon value goes here> {
<CSS style definition goes here, such as primarily the image path>
CSS:
.ui-icon-iphonecheck {
background-image: url('images/bluecheck.png');
}
<a
href="#"
data-role="button"
data-icon="iphonecheck"
>Mystuff</a>
To use custom icons, specify a data-icon value that has a unique name like myapp-email and the button plugin will generate a class by prefixing ui-icon- to the data-icon value and apply it to the button. You can then write a CSS rule that targets the ui-icon-myapp-email class to specify the icon background source. To maintain visual consistency, create a white icon 18x18 pixels saved as a PNG-8 with alpha transparency.
- Side-by-Side Alignment
data-inline="true"
<div
data-inline="true">
<a href="#" data-role="button">Cancel</a>
<a href="#" data-role="button">Save</a>
</div>
By default, all buttons in the body content are styled as block-level element so they fill the width of the screen. If you have multiple buttons that should sit side-by-side on the same line, wrap the buttons in a container that has a data-inline="true" attribute. This will style the buttons to be the width of their content and float the buttons so they sit on the same line.
- Grouped (Stacked Vertically)
data-role="controlgroup"
<div
data-role="controlgroup">
<a href="index.html" data-role="button">Yes</a>
<a href="index.html" data-role="button">No</a>
<a href="index.html" data-role="button">Maybe</a>
</div>
- Horizontal Grouping
data-type="horizontal"
<div data-role="controlgroup"
data-type="horizontal">
<a href="index.html" data-role="button">Yes</a>
<a href="index.html" data-role="button">No</a>
<a href="index.html" data-role="button">Maybe</a>
</div>
Docs&Demos
By adding the data-type="horizontal" attribute to the controlgroup container, you can swap to a horizontal-style group that floats the buttons side-by-side and sets the width to only be large enough to fit the content. (Be aware that these will wrap to multiple lines if the number of buttons or the overall text length is too wide for the screen.)
- Active State
class="ui-btn-active"
class="ui-btn-active"
The jQuery Mobile framework uses a single Theme-level swatch called "active" (bright blue in the default theme) to consistently indicate the selected state, regardless of the individual swatch of the given widget. We apply this in navigation and form controls whenever there is a need to indicate what is currently selected. Because this theme swatch is designed for clear, consistent user feedback, it cannot be overridden via the markup; it is set once in the Theme and applied by the framework whenever a selected or active state is needed. The styling for this state is in the theme stylesheet under the ui-btn-active style rules.
- Columns
- 2-Column Grid
class="ui-grid-a"
class="ui-block-a"
class="ui-block-b"
<div
class="ui-grid-a">
<div
class="ui-block-a">I'm Block A</div>
<div
class="ui-block-b">I'm Block B</div>
</div><!-- /grid-a -->
- 3-Column Grid
class="ui-grid-b"
class="ui-block-a"
class="ui-block-b"
class="ui-block-c"
<div
class="ui-grid-b">
<div class="ui-block-a">Block A</div>
<div class="ui-block-b">Block B</div>
<div class="ui-block-c">Block C</div>
</div><!-- /grid-b -->
- 4-Column Grid
class="ui-grid-c"
class="ui-grid-c"
- 5-Column Grid
class="ui-grid-d"
class="ui-grid-d"
- Collapsible Blocks
- Declaration
data-role="collapsible"
<div
data-role="collapsible">
<h3>I'm a header</h3>
<p>I'm the collapsible content. By default I'm open and displayed on the page, but you can click the header to hide me.</p>
</div>
Docs&Demos
To create a collapsible blocks of content, create a container and add the data-role="collapsible" attribute.
Directly inside this container, add any header element (H1-H6). The framework will style the header to look like a clickable button and add a "+" icon to the left to indicate it's expandable.
- Default to Collapsed
data-collapsed="true"
data-collapsed="true"
As the example notes, by default the content will be expanded. To collapse the content when the page loads, add the data-collapsed="true" attribute to the wrapper.
- Forms
- Unique IDs
id
id
When constructing forms to be used in jQuery Mobile, most of the standard guidelines used to create forms that submit via normal HTTP post or get still apply. However, one thing to keep in mind is that the id attributes of form controls need to be not only unique on a given page, but also unique across the pages in a site.
- Preventing Formatting
data-role="none"
<label for="foo">
<select name="foo" id="foo" data-role="none">
<option value="a" >A</option>
<option value="b" >B</option>
<option value="c" >C</option>
</select>
If you'd prefer that a particular form control be left untouched by jQuery Mobile, simply give that element the attribute data-role="none". Adding the data-role="none" attribute to any form or button element tells the framework to not apply any enhanced styles or scripting.
- Mobile Formatting
data-role="fieldcontain"
<div data-role="fieldcontain">
...label/input code goes here...
</div>
<div data-role="fieldcontain">
<label for="name">Text Input:</label>
<input type="text" name="name" id="name" value="" />
</div>
To improve the styling to labels and form elements on wider screens, we recommend wrapping a div or fieldset with the data-role="fieldcontain" attribute around each label/form element. The framework will add a thin vertical bottom border on this container to act as a field separator and visually align the label and form elements for quick scanning.
- Non-Ajax Handling
data-ajax="false"
data-ajax="false"
To prevent form submissions from being automatically handled with Ajax, add the data-ajax="false" attribute to the form element. You can also turn of Ajax form handling completely via the ajaxEnabled global config option.
- Lists
- List Declaration
data-role="listview"
<ul
data-role="listview" data-theme="g">
<li><a href="acura.html">Acura</a></li>
<li><a href="audi.html">Audi</a></li>
<li><a href="bmw.html">BMW</a></li>
</ul>
Docs&Demos
A list view is coded as a simple unordered list containing linked list items with a data-role="listview" attribute. jQuery Mobile will apply all the necessary styles to transform the list into a mobile-friendly list view with right arrow indicator that fills the full width of the browser window. When you tap on the list item, the framework will trigger a click on the first link inside the list item, issue an AJAX request for the URL in the link, create the new page in the DOM, then kick off a page transition.
- Display Item Counts
class="ui-li-count"
class="ui-li-count"
Docs&Demos
To add a count indicator to the right of the list item, wrap the number in an element with a class of ui-li-count
- Supplemental Text
class="ui-li-aside"
class="ui-li-icon"
Docs&Demos
Supplemental information can be added to the right of each list item by wrapping content in an element with a class of ui-li-aside
- Thumbnail Images
To add thumbnails to the left of a list item, simply add an image inside a list item as the first child element. The framework will scale the image to 80 pixels square.
- Icon-Sized Images
class="ui-li-icon"
To use standard 16x16 pixel icons in list items, add the class of ui-li-icon to the image element to size.
- Inset Lists
data-inset="true"
data-inset="true"
If lists are embedded in a page with other types of content, an inset list packages the list into a block that sits inside the content area with a bit of margin and rounded corners (theme controlled). By adding the data-inset="true" attribute to the list (ul or ol), applies the inset appearance.
- Dynamically Updating Lists
$('ul').listview('refresh');
N/A
If you add items to a listview, you'll need to call the refresh() method on it to update the styles and create any nested lists that are added. For example, $('ul').listview('refresh');
- 2-Column Lists (Two)
data-split-icon
data-split-theme
In cases where there is more than one possible action per list item, a split button can be used to offer two independently clickable items -- the list item and a small arrow icon in the far right. To make a split list item, simply add a second link inside the li and the framework will add a vertical divider line, style the link as an icon-only arrow button, and sets the title attribute of the link to the text the link for accessibility.
You can set the icon for the right split icon by specifying a data-split-icon attribute with the icon name you want. The theme swatch color of the split button can be set by specifying a swatch letter in the data-split-theme attribute
- List Dividers
data-role="list-divider"
data-dividertheme="a"
<ul
data-role="listview"
data-theme="c"
data-dividertheme="b">
<li data-role="list-divider">List Dividers</li>
List items can be turned into dividers to organize and group the list items. This is done by adding the data-role="list-divider" to any list item. These items are styled with the body swatch "b" by default (light gray in the default theme) but you can specify a theme for dividers by adding the data-dividertheme attribute to the list element (ul or ol) and specifying a theme swatch letter.
- Search/Filter-able List
data-filter="true"
<ul
data-role="listview"
data-filter="true">
jQuery Mobile provides a very easy way to filter a list with a simple client-side search feature. To make a list filterable, simply add the data-filter="true" attribute to the list. The framework will then append a search box above the list and add the behavior to filter out list items that don't contain the current search string as the user types. The input's placeholder text defaults to "Filter items...". To configure the placeholder text in the search input, you can either bind to the mobileinit event and set the $.mobile.listview.prototype.options.filterPlaceholder option to a string of your choosing, or use the data-attribute data-filter-placeholder on your listview. By default the search box will inherit its theme from its parent. The search box theme can be configured using the data-attribute data-filter-theme on your listview.
- Theming
- Data Theme Declaration
data-theme="b"
<div data-role="header" data-theme="b">
<h1>Page Title</h1>
</div>
Docs&Demos
jQuery Mobile's default Theme includes 5 swatches that are given letters (a, b, c, d, e) for quick reference. To make mapping of color swatches consistent across our widgets, we have followed the convention that swatch "a" is the highest level of visual priority (black in our default theme), "b" is secondary level (blue) and "c" is the baseline level (gray) that we use by default in many situations, "d" for an alternate secondary level and "e" as an accent swatch. Themes may have additional swatches for accent colors or specific situations. For example, you could add a new theme swatch "f" that has a red bar and button for use in error situations.