jQuery Mobile Data Attributes
jQuery Data Attributes
jQuery Mobile uses HTML5 data-* attributes to create a more touch-friendly and appealing appearance for mobile devices.
In the reference list below, bold values are the defaults.
Buttons
Hyperlinks with data-role="button". Button elements, links in toolbars, and input fields are automatically styled as buttons without needing to add data-role="button".
| Data-Attribute | Value | Description | ||||
|---|---|---|---|---|---|---|
| data-corners | true | false | Specifies if the button has rounded corners | |||
| data-icon | Icon Reference | Specifies the icon for the button. No icon by default. | ||||
| data-iconpos | left | right | top | bottom | notext | Specifies the position of the icon |
| data-iconshadow | true | false | Specifies if the button icon has a shadow | |||
| data-inline | true | false | Specifies if the button is inline | |||
| data-mini | true | false | Specifies if the button is small or regular size | |||
| data-shadow | true | false | Specifies if the button has a shadow | |||
| data-theme | letter (a-z) | Specifies the theme color of the button |
| | To group multiple buttons, use a container with data-role="controlgroup" and data-type="horizontal|vertical" to specify whether to group buttons horizontally or vertically. |
| --- | --- |
Checkboxes
Pairs of labels and inputs with type="checkbox". They are automatically styled as buttons, and data-role is not required.
| Data-Attribute | Value | Description | |
|---|---|---|---|
| data-mini | true | false | Specifies if the checkbox is small or regular size |
| data-role | none | Prevents jQuery Mobile from styling the checkbox as a button | |
| data-theme | letter (a-z) | Specifies the theme color of the checkbox |
| | To group multiple checkboxes, use a container with data-role="controlgroup" and data-type="horizontal|vertical" to specify whether to group checkboxes horizontally or vertically. |
| --- | --- |
Collapsible Blocks
A header element followed by any HTML markup inside a container with data-role="collapsible".
| Data-Attribute | Value | Description | |||
|---|---|---|---|---|---|
| data-collapsed | true | false | Specifies if the content is collapsed or expanded | ||
| data-collapsed-icon | Icon Reference | Specifies the icon for the collapsible button. Default is "plus" | |||
| data-content-theme | letter (a-z) | Specifies the theme color of the collapsible content. Adds rounded corners to the collapsible content | |||
| data-expanded-icon | Icon Reference | Specifies the icon for the collapsible button when the content is expanded. Default is "minus" | |||
| data-iconpos | left | right | top | bottom | Specifies the position of the icon |
| data-inset | true | false | Specifies if the collapsible button is rendered with rounded corners and margin | ||
| data-mini | true | false | Specifies if the collapsible button is small or regular size | ||
| data-theme | letter (a-z) | Specifies the theme color of the collapsible button |
Collapsible Sets
Collapsible content blocks inside a container with data-role="collapsible-set".
| Data-Attribute | Value | Description | ||||
|---|---|---|---|---|---|---|
| data-collapsed-icon | Icon Reference | Specifies the icon for the collapsible button. Default is "plus" | ||||
| data-content-theme | letter (a-z) | Specifies the theme color of the collapsible button | ||||
| data-expanded-icon | Icon Reference | Specifies the icon for the collapsible button when the content is expanded. Default is "minus" | ||||
| data-iconpos | left | right | top | bottom | notext | Specifies the position of the icon |
| data-inset | true | false | Specifies if the collapsible blocks are rendered with rounded corners and margin | |||
| data-mini | true | false | Specifies if the collapsible button is small or regular size | |||
| data-theme | letter (a-z) | Specifies the theme color of the collapsible set |
Content
A container with data-role="content".
| Data-Attribute | Value | Description |
|---|---|---|
| data-theme | letter (a-z) | Specifies the theme color of the content. |
Control Groups
A <div> or <fieldset> container with data-role="controlgroup". Groups multiple button-styled inputs of a single type (link-based buttons, radio buttons, checkboxes, select elements). For grouping form checkboxes and radio buttons, it is recommended to use a <fieldset> container inside a <div> with data-role="fieldcontain" to improve label styling.
| Data-Attribute | Value | Description | |
|---|---|---|---|
| data-mini | true | false | Specifies if the control group is small or regular size |
| data-type | horizontal | vertical | Specifies if the control group is displayed horizontally or vertically |
Dialogs
A container with data-role="dialog" or a link with data-rel="dialog".
| Data-Attribute | Value | Description | |
|---|---|---|---|
| data-close-btn-text | sometext | Specifies the text for the dialog close button | |
| data-dom-cache | true | false | Specifies whether to clear the jQuery DOM cache for each page (if set to true, you must manage the DOM yourself and test on all devices) |
| data-overlay-theme | letter (a-z) | Specifies the mask (background) color for the dialog page | |
| data-theme | letter (a-z) | Specifies the theme color for the dialog page | |
| data-title | sometext | Specifies the title for the dialog page |
Enhancements
A container with data-enhance="false" or data-ajax="false".
| Data-Attribute | Value | Description | |
|---|---|---|---|
| data-enhance | true | false | If set to "true" (default), jQuery Mobile automatically renders the page to be more mobile-friendly. If set to "false", the framework will not render the page |
| data-ajax | true | false | Specifies whether to load the page via ajax |
Note: data-enhance="false" must be used with $.mobile.ignoreContentEnabled=true to prevent jQuery Mobile from automatically rendering the page.
When $.mobile.ignoreContentEnabled is set to true, any links or form elements within the data-ajax="false" container will be ignored by the framework's navigation features.
Field Containers
A container with data-role="fieldcontain".
Fixed Toolbars
A container with data-role="header" or data-role="footer" and data-position="fixed".
| Data-Attribute | Value | Description | ||
|---|---|---|---|---|
| data-disable-page-zoom | true | false | Specifies if the user can zoom the page | |
| data-fullscreen | true | false | Specifies if the toolbar is always fixed at the top or bottom | |
| data-tap-toggle | true | false | Specifies if the user can change the toolbar's visibility by tapping | |
| data-transition | slide | fade | none | Specifies the transition effect when a tap occurs |
| data-update-page-padding | true | false | Specifies if the page padding at the top and bottom is updated when resize, transition, and "updatelayout" events occur (jQuery Mobile always updates padding on "pageshow" event) | |
| data-visible-on-page-show | true | false | Specifies the toolbar's visibility when the parent page is shown |
Flip Toggle Switches
A <select> element with data-role="slider" and two <option> elements.
| Data-Attribute | Value | Description | |
|---|---|---|---|
| data-mini | true | false | Specifies if the switch is small or regular size |
| data-role | none | Prevents jQuery Mobile from styling the toggle switch as a button | |
| data-theme | letter (a-z) | Specifies the theme color of the toggle switch | |
| data-track-theme | letter (a-z) | Specifies the theme color of the track |
Footer Bars
A container with data-role="footer".
| Data-Attribute | Value | Description | |
|---|---|---|---|
| data-id | sometext | Specifies a unique ID. Required for persistent footer bars | |
| data-position | inline | fixed | Specifies if the footer bar is inline with the page content or stays fixed at the bottom |
| data-fullscreen | true | false | Specifies if the footer bar is fixed at the bottom or overlays the page content (for a larger viewing area) |
| data-theme | letter (a-z) | Specifies the theme color of the footer bar. Default is "a" |
Note: To enable fullscreen positioning, use data-position="fixed" and add the data-fullscreen attribute to the element.
Header Bars
A container with data-role="header".
| Data-Attribute | Value | Description | |
|---|---|---|---|
| data-id | sometext | Specifies a unique ID. Required for persistent header bars | |
| data-position | inline | fixed | Specifies if the header bar is inline with the page content or stays fixed at the top |
| data-fullscreen | true | false | Specifies whether the header bar is fixed at the top or overlays the page content (for a larger viewing area) |
| data-theme | Letter (a-z) | Specifies the theme color of the header bar. The default is "a" |
Note: To enable fullscreen positioning, use data-position="fixed" and then add the data-fullscreen attribute to the element.
Links
All links, including those with data-role="button" and form submission buttons.
| Data-attribute | Value | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| data-ajax | true | false | Specifies whether to load pages via ajax to enhance user experience and interaction. If set to false, jQuery Mobile will perform a normal page request. | ||||||||
| data-direction | reverse | Reverse transition animation (only for pages and dialogs) | |||||||||
| data-dom-cache | true | false | Specifies whether to clear the jQuery DOM cache for each page (if set to true, you must manage the DOM yourself and test on all mobile devices) | ||||||||
| data-prefetch | true | false | Specifies whether to pre-fetch pages into the DOM so they are available when the user visits them | ||||||||
| data-rel | back | dialog | external | popup | Specifies the options for link behavior. Back - Goes back to the previous page in the history. Dialog - Opens the link as a dialog, not saved in history. External - Used for linking to another domain. Popup - Opens a popup window. | ||||||
| data-transition | fade | flip | flow | pop | slide | slidedown | slidefade | slideup | turn | none | Specifies the effect for transitioning from one page to the next. See our jQuery Mobile Page Transitions |
| data-position-to | origin | jQuery selector | window | Specifies the position of the popup. Origin - Default. Positions the popup on the link that opens it. jQuery selector - Positions the popup on a specified element. Window - Positions the popup in the center of the window screen. |
Lists
<ol> or <ul> with data-role="listview".
| Data-attribute | Value | Description | |
|---|---|---|---|
| data-autodividers | true | false | Specifies whether to automatically divide list items |
| data-count-theme | Letter (a-z) | Specifies the theme color for the count bubble. | |
| data-divider-theme | Letter (a-z) | Specifies the theme color for the list divider. | |
| data-filter | true | false | Specifies whether to add a search box in the list |
| data-filter-placeholder | sometext | Deprecated after version 1.4. Use the HTML placeholder attribute instead. Specifies the text inside the search box. The default is "Filter items..." | |
| data-filter-theme | Letter (a-z) | Specifies the theme color for the search filter. | |
| data-icon | Icon Reference Manual | Specifies the icon for the list | |
| data-inset | true | false | Specifies whether the list is rendered with rounded corners and margin |
| data-split-icon | Icon Reference Manual | Specifies the icon for the split button. The default is "arrow-r" | |
| data-split-theme | Letter (a-z) | Specifies the theme color for the split button. | |
| data-theme | Letter (a-z) | Specifies the theme color for the list |
List Items
<li> inside <ol> or <ul> with data-role="listview".
| Data-attribute | Value | Description |
|---|---|---|
| data-filtertext | sometext | Specifies the text to search for when filtering elements. This text will be filtered instead of the actual list item text |
| data-icon | Icon Reference Manual | Specifies the icon for the list item |
| data-role | list-divider | Specifies the divider for the list item |
| data-theme | Letter (a-z) | Specifies the theme color for the list item |
Note: The data-icon attribute only works on list items with links.
Navigation Bars
<li> elements inside a container with data-role="navbar".
| Data-attribute | Value | Description | ||||
|---|---|---|---|---|---|---|
| data-icon | Icon Reference Manual | Specifies the icon for the list item | ||||
| data-iconpos | left | right | top | bottom | notext | Specifies the position of the icon |
| | Navigation bars inherit theme swatches from their parent container. It is not possible to set a data-theme attribute for the navbar. You can set the data-theme attribute individually for each link in the navbar. | | --- | --- |
Pages
Containers with data-role="page".
| Data-attribute | Value | Description | |
|---|---|---|---|
| data-add-back-btn | true | false | Automatically adds a back button, only for header bars |
| data-back-btn-text | sometext | Specifies some text for the back button | |
| data-back-btn-theme | Letter (a-z) | Specifies the theme color for the back button | |
| data-close-btn-text | Letter (a-z) | Specifies some text for the close button on dialogs | |
| data-dom-cache | true | false | Specifies whether to clear the jQuery DOM cache for each page (if set to true, you must manage the DOM yourself and test on all mobile devices) |
| data-overlay-theme | Letter (a-z) | Specifies the mask (background) color for dialog pages | |
| data-theme | Letter (a-z) | Specifies the theme color for the page. | |
| data-title | sometext | Specifies the page title | |
| data-url | url | Updates the value of the URL, rather than the URL used to request the page |
Popups
Containers with data-role="popup".
| Data-attribute | Value | Description | |
|---|---|---|---|
| data-corners | true | false | Specifies whether the popup has rounded corners |
| data-overlay-theme | Letter (a-z) | Specifies the mask (background) color for the popup. The default is a transparent background (none) | |
| data-shadow | true | false | Specifies whether the popup has a shadow |
| data-theme | Letter (a-z) | Specifies the theme color for the popup. The default is inherited, "none" sets the popup to transparent | |
| data-tolerance | 30, 15, 30, 15 | Specifies the distance from the window edges (top, right, bottom, left) |
Anchors with data-rel="popup":
| Data-attribute | Value | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| data-position-to | origin | jQuery selector | window | Specifies the position of the popup. Origin - Default. Positions the popup on the link that opens it. jQuery selector - Positions the popup on a specified element. Window - Positions the popup in the center of the window screen. | |||||||
| data-rel | popup | Used to open the popup | |||||||||
| data-transition | fade | flip | flow | pop | slide | slidedown | slidefade | slideup | turn | none | Specifies the effect for transitioning from one page to the next. See our jQuery Mobile Page Transitions |
Radio Buttons
Paired labels and inputs with type="radio". They are automatically rendered as button styles, data-role is not required.
| Data-attribute | Value | Description | |
|---|---|---|---|
| data-mini | true | false | Specifies whether the button is small or regular size |
| data-role | none | Prevents jQuery Mobile from rendering the radio button style as an enhanced button, displaying the element in its native HTML state | |
| data-theme | Letter (a-z) | Specifies the theme color for the radio button |
| | To group multiple radio buttons, use a container with the data-role="controlgroup" attribute and data-type="horizontal|vertical" to specify whether to group the radio buttons horizontally or vertically. | | --- | --- |
Selects
All <select> elements. These are automatically rendered as button styles, data-role is not required.
| Data-attribute | Value | Description | ||||
|---|---|---|---|---|---|---|
| data-icon | Icon Reference Manual | Specifies the icon for the select element. The default is "arrow-d" | ||||
| data-iconpos | left | right | top | bottom | notext | Specifies the position of the icon |
| data-inline | true | false | Specifies whether the select element is inline | |||
| data-mini | true | false | Specifies whether the select element is small or regular size | |||
| data-native-menu | true | false | When set to false, it uses jQuery's custom select menu (recommended if you want the select menu to look the same across all mobile devices) | |||
| data-overlay-theme | Letter (a-z) | Specifies the theme color for jQuery's custom select menu (used with data-native-menu="false") | ||||
| data-placeholder | true | false | Can be set on a non-native select menu's <option> element | |||
| data-role | none | Prevents jQuery Mobile from rendering the select element as a button style | ||||
| data-theme | Letter (a-z) | Specifies the theme color for the select element |
| | To group multiple select elements, use a container with the data-role="controlgroup" attribute and data-type="horizontal|vertical" to specify whether to group the select elements horizontally or vertically. | | --- | --- |
Sliders
Containers with data-role="slider".
Input fields with type="range". These are automatically rendered in button style, and data-role is not necessary.
| Data-attribute | Value | Description | |
|---|---|---|---|
| data-highlight | true | false | Specifies whether the slider track is highlighted |
| data-mini | true | false | Specifies whether the slider is small or regular size |
| data-role | none | Prevents jQuery Mobile from rendering the slider control as a button style | |
| data-theme | letter (a-z) | Specifies the theme color for the slider control (input, handle, and track) | |
| data-track-theme | letter (a-z) | Specifies the theme color for the slider track |
Text Input Fields & Text Areas
Inputs with type="text|search|etc." or textarea elements. These are automatically rendered in button style, and data-role is not necessary.
| Data-attribute | Value | Description | |
|---|---|---|---|
| data-mini | true | false | Specifies whether the input field is small or regular size |
| data-role | none | Prevents jQuery Mobile from rendering the input field/area as a button style | |
| data-theme | letter (a-z) | Specifies the theme color for the input field |