jQuery Data Attributes
jQuery Mobile uses the HTML5 data-* attribute to create a "touch-friendly" and attractive look for mobile devices.
For the reference list below, bold value specifies the default value.
Button
Deprecated in version 1.4. Use CSS Classes instead. Hyperlinks with data-role="button". Button elements and links in toolbars and input fields are automatically styled as buttons, no need for data-role="button".
| Data-attribute | Value | Description |
|---|---|---|
| data-corners | true | false | Specifies whether the button should have rounded corners or not |
| data-icon | Icons Reference | Specifies the icon of the button. Default is no icon |
| data-iconpos | left | right | top | bottom | notext | Specifies the position of the icon |
| data-iconshadow | true | false | Specifies whether the button icon should have shadows or not |
| data-inline | true | false | Specifies whether the button should be inline or not |
| data-mini | true | false | Specifies whether the button should be of small or regular size |
| data-shadow | true | false | Specifies whether the button should have shadows or not |
| data-theme | letter (a-z) | Specifies the theme color of the button |
To group multiple buttons, use a container with the data-role="controlgroup" attribute together with data-type="horizontal|vertical" to specify whether to group buttons horizontally or vertically.
Checkbox
Pairs of labels and inputs with type="checkbox".
| Data-attribute | Value | Description |
|---|---|---|
| data-mini | true | false | Specifies whether the checkbox should be of small or regular size |
| data-role | none | Prevents jQuery Mobile to style checkboxes as buttons |
| data-theme | letter (a-z) | Specifies the theme color of the checkbox |
To group multiple checkboxes, use the data-role="controlgroup" together with the data-type="horizontal|vertical" to specify whether to group checkboxes horizontally or vertically.
Collapsible
A header element followed by any HTML markup inside a container with the data-role="collapsible".
| Data-attribute | Value | Description |
|---|---|---|
| data-collapsed | true | false | Specifies whether the content should be closed or expanded |
| data-collapsed-cue-text | sometext | Specifies some text to provide audible feedback for users with screen reader software. Default is "click to collapse contents". |
| data-collapsed-icon | Icons Reference | Specifies the icon of the collapsible button. Default is "plus" |
| data-content-theme | letter (a-z) | Specifies the theme color of the collapsible content. Will also add rounded corners to the collapsible content |
| data-expanded-cue-text | sometext | Specifies some text to provide audible feedback for users with screen reader software. Default is "click to expand contents". |
| data-expanded-icon | Icons Reference | Specifies the icon of 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 whether the collapsible button should be styled with rounded corners and some margin or not |
| data-mini | true | false | Specifies whether the collapsible buttons should be of small or regular size |
| data-theme | letter (a-z) | Specifies the theme color of the collapsible button |
Collapsible Set
Collapsible content blocks inside a container with the data-role="collapsibleset".
| Data-attribute | Value | Description |
|---|---|---|
| data-collapsed-icon | Icons Reference | Specifies the icon of the collapsible button. Default is "plus" |
| data-content-theme | letter (a-z) | Specifies the theme color of the collapsible content |
| data-expanded-icon | Icons Reference | Specifies the icon of 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 whether the collapsibles should be styled with rounded corners and some margin or not |
| data-mini | true | false | Specifies whether the collapsible buttons should be of small or regular size |
| data-theme | letter (a-z) | Specifies the theme color of the collapsible set |
Content
Deprecated in version 1.4, and will be removed in 1.5. Container with data-role="content".
| Data-attribute | Value | Description |
|---|---|---|
| data-theme | letter (a-z) | Specifies the theme color of the content |
Controlgroup
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, the <fieldset> container is recommended inside a <div> with the "ui-fieldcontain" class, to improve label styling.
| Data-attribute | Value | Description |
|---|---|---|
| data-exclude-invisible | true | false | Specifies whether to exclude invisible children in the assignment of rounded corners |
| data-mini | true | false | Specifies whether the group should be of small or regular size |
| data-theme | letter (a-z) | Specifies the theme color of the controlgroup |
| data-type | horizontal | vertical | Specifies whether the group should be horizontally or vertically displayed |
Dialog
A container with data-dialog="true".
| Data-attribute | Value | Description |
|---|---|---|
| data-close-btn | left | right | none | Specifies the position of the close button |
| data-close-btn-text | sometext | Specifies the text for the close button |
| data-corners | true | false | Specifies whether the dialog should have rounded corners or not |
| data-dom-cache | true | false | Specifies whether the to clear jQuery DOM cache or not for individual pages (if set to true, you need to take care to manage the DOM yourself and test thoroughly on all mobile devices) |
| data-overlay-theme | letter (a-z) | Specifies the overlay (background) color of the dialog page |
| data-theme | letter (a-z) | Specifies the theme color of the dialog page |
| data-title | sometext | Specifies the title for the dialog page |
Enhancement
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 will automatically style the page, making it suitable for mobile devices. If set to "false", the framework will not style the page |
| data-ajax | true | false | Specifies whether to load pages via ajax or not |
Note: data-enhance="false" must be used in conjunction with $.mobile.ignoreContentEnabled=true" to stop jQuery Mobile to style pages automatically.
Any link or form element inside data-ajax="false" containers will be ignored by the framework's navigation functionality when $.mobile.ignoreContentEnabled is set to true.
Field Container
Deprecated in version 1.4, and will be removed in 1.5. Use class="ui-fieldcontain instead". A container with data-role="fieldcontain" wrapped around label/form element pair.
Fixed Toolbar
A container with data-role="header" or data-role="footer" together with the data-position="fixed" attribute.
| Data-attribute | Value | Description |
|---|---|---|
| data-disable-page-zoom | true | false | Specifies whether the user is able to scale/zoom the page or not |
| data-fullscreen | true | false | Specifies toolbars to always be positioned at the top and/or bottom |
| data-tap-toggle | true | false | Specifies whether the user is able to toggle toolbar-visibility on taps/clicks or not |
| data-transition | slide | fade | none | Specifies the transition effect when a tap/click occurs |
| data-update-page-padding | true | false | Specifies the padding of both top and bottom of the page to be updated on resize, transition and "updatelayout" events (jQuery Mobile always updates the padding on the "pageshow" event) |
| data-visible-on-page-show | true | false | Specifies toolbar-visibility when parent page is shown |
Flip Toggle Switch
An <input type="checkbox"> with a data-role of "flipswitch":
| Data-attribute | Value | Description |
|---|---|---|
| data-mini | true | false | Specifies whether the switch should be of small or regular size |
| data-on-text | sometext | Specifies the "on" text on the flip switch (default is "On") |
| data-off-text | sometext | Specifies the "off" text on the flip switch (default is "Off") |
Footer
A container with data-role="footer".
| Data-attribute | Value | Description |
|---|---|---|
| data-id | sometext | Specifies a unique ID. Required for persistent footers |
| data-position | inline | fixed | Specifies whether the footer should be inline with page content or remain positioned at the bottom |
| data-fullscreen | true | false | Specifies whether the footer should always be positioned at the bottom and over the page content (slightly see-through) or not |
| data-theme | letter (a-z) | Specifies the theme color of the footer |
Note: To enable the fullscreen position, use data-position="fixed" and then add the data-fullscreen attribute to the element.
Header
A container with data-role="header".
| Data-attribute | Value | Description |
|---|---|---|
| data-id | sometext | Specifies a unique ID. Required for persistent headers |
| data-position | inline | fixed | Specifies whether the header should be inline with page content or remain positioned at the top |
| data-fullscreen | true | false | Specifies whether the header should always be positioned at the top and over the page content (slightly see-through) or not |
| data-theme | letter (a-z) | Specifies the theme color of the header |
Note: To enable the fullscreen position, use data-position="fixed" and then add the data-fullscreen attribute to the element.
Inputs
Inputs with type="text|search|etc." or textarea elements.
| Data-attribute | Value | Description |
|---|---|---|
| data-clear-btn | true | false | Specifies whether the input should have a "clear" button |
| data-clear-btn-text | text | Specifies a text for the "clear" button. Default is "clear text" |
| data-mini | true | false | Specifies whether the input should be of small or regular size |
| data-role | none | Prevents jQuery Mobile to style inputs/textareas as buttons |
| data-theme | letter (a-z) | Specifies the theme color of the input field |
Link
All links.
| Data-attribute | Value | Description |
|---|---|---|
| data-ajax | true | false | Specifies whether to load pages via ajax for improved user experience and transitions. If set to false, jQuery Mobile will do a normal page request. |
| data-direction | reverse | Reverse transition animation (only for page or dialog) |
| data-dom-cache | true | false | Specifies whether the to clear jQuery DOM cache or not for individual pages (if set to true, you need to take care to manage the DOM yourself and test thoroughly on all mobile devices) |
| data-prefetch | true | false | Specifies whether to prefetch pages into the DOM so that they are available when the user visits them |
| data-rel | back | dialog | external | popup | Specifies an option for how the link should behave. Back - Moves one step back in history. Dialog - Opens a link as a dialog, not tracked in history. External - For linking to another domain. Popup - opens a popup window. |
| data-transition | fade | flip | flow | pop | slide | slidedown | slidefade | slideup | turn | none | Specifies how to transition from one page to the next. See our jQuery Mobile Transitions chapter. |
| data-position-to | origin | jQuery selector | window | Specifies the position of popup boxes. Origin - Default. Positions the popup over the link that opens it. jQuery selector - positions the popup over the specified element. Window - positions the popup in the middle of the window screen. |
List
An <ol> or <ul> with data-role="listview".
| Data-attribute | Value | Description |
|---|---|---|
| data-autodividers | true | false | Specifies whether to automatically divide list items or not |
| data-count-theme | letter (a-z) | Specifies the theme color of the count bubble |
| data-divider-theme | letter (a-z) | Specifies the theme color of the list divider |
| data-filter | true | false | Specifies whether to add a search box in a list or not |
| data-filter-placeholder | sometext | Deprecated in version 1.4. Use the HTML placeholder attribute instead. Specifies the text inside the search box. Default is "Filter items..." |
| data-filter-theme | letter (a-z) | Specifies the theme color of the search filter |
| data-icon | Icons Reference | Specifies the icon of the list |
| data-inset | true | false | Specifies whether the list should be styled with rounded corners and some margin or not |
| data-split-icon | Icons Reference | Specifies the icon of the split button. Default is "arrow-r" |
| data-split-theme | letter (a-z) | Specifies the theme color of the split button |
| data-theme | letter (a-z) | Specifies the theme color of the list |
List item
An <li> inside an <ol> or <ul> with data-role="listview".
| Data-attribute | Value | Description |
|---|---|---|
| data-filtertext | sometext | Specifies a text to search for when filtering elements. This text will then be filtered instead of the actual list item text |
| data-icon | Icons Reference | Specifies the icon of the list item |
| data-role | list-divider | Specifies a divider for list items |
| data-theme | letter (a-z) | Specifies the theme color of the list item |
Note: The data-icon attribute only work on list items with links.
Navbar
<li> elements inside a container with data-role="navbar".
| Data-attribute | Value | Description |
|---|---|---|
| data-icon | Icons Reference | Specifies the icon of the list item |
| data-iconpos | left | right | top | bottom | notext | Specifies the position of the icon |
Navbars inherit the theme-swatch from their parent container. It is not possible to set the data-theme attribute to a navbar. The data-theme attribute can be set individually to each link inside the navbar.
Page
A container with data-role="page".
| Data-attribute | Value | Description |
|---|---|---|
| data-dom-cache | true | false | Specifies whether the to clear jQuery DOM cache or not for individual pages (if set to true, you need to take care to manage the DOM yourself and test thoroughly on all mobile devices) |
| data-overlay-theme | letter (a-z) | Specifies the overlay (background) color of dialog pages |
| data-theme | letter (a-z) | Specifies the theme color of the page |
| data-title | sometext | Specifies the page title |
| data-url | url | Value for updating the URL, instead of the url used to request the page |
Popup
A container with data-role="popup".
| Data-attribute | Value | Description |
|---|---|---|
| data-corners | true | false | Specifies whether the popup should have rounded corners or not |
| data-dismissible | true | false | Specifies whether the popup should be closed by clicking outside of the popup or not |
| data-history | true | false | Specifies whether the popup should create a browser history item when opened. If set to false, it will not create a history item, and will then not be closeable via the browser's "Back" button |
| data-overlay-theme | letter (a-z) | Specifies the overlay (background) color of the popup box. Default is transparent background (none). |
| data-shadow | true | false | Specifies whether the popup box should have shadows or not |
| data-theme | letter (a-z) | Specifies the theme color of the popup box. Default inherited, "none" sets the popup to transparent |
| data-tolerance | 30, 15, 30, 15 | Specifies the distance from the edges of the window (top, right, bottom, left) |
An anchor with data-rel="popup":
| Data-attribute | Value | Description |
|---|---|---|
| data-position-to | origin | jQuery selector | window | Specifies the position of popup boxes. Origin - Default. Positions the popup over the link that opens it. jQuery selector - positions the popup over the specified element. Window - positions the popup in the middle of the window screen. |
| data-rel | popup | For opening the popup box |
| data-transition | fade | flip | flow | pop | slide | slidedown | slidefade | slideup | turn | none | Specifies how to transition from one page to the next. See our jQuery Mobile Transitions chapter. |
Radio Button
Pairs of labels and inputs with type="radio".
| Data-attribute | Value | Description |
|---|---|---|
| data-mini | true | false | Specifies whether the button should be of small or regular size |
| data-role | none | Prevents jQuery Mobile to style radiobuttons as enhanced buttons |
| data-theme | letter (a-z) | Specifies the theme color of the radio button |
To group multiple radio buttons, use the data-role="controlgroup" together with the data-type="horizontal|vertical" to specify whether to group the buttons horizontally or vertically.
Select
All <select> elements.
| Data-attribute | Value | Description |
|---|---|---|
| data-icon | Icons Reference | Specifies the icon of the select element. 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 should be inline or not |
| data-mini | true | false | Specifies whether the select should be of small or regular size |
| data-native-menu | true | false | When set to false, it uses jQuery's own custom select menu (recommended if you want the select menu to display the same on all mobile devices) |
| data-overlay-theme | letter (a-z) | Specifies the theme color of jQuery's own custom select menu (used together with data-native-menu="false") |
| data-placeholder | true | false | Can be set on an <option> element of a non-native select |
| data-role | none | Prevents jQuery Mobile to style select elements as buttons |
| data-theme | letter (a-z) | Specifies the theme color of the select element |
To group multiple select elements, use the data-role="controlgroup" together with the data-type="horizontal|vertical" to specify whether to group the elements horizontally or vertically.
Slider
Inputs with type="range".
| Data-attribute | Value | Description |
|---|---|---|
| data-highlight | true | false | Specifies whether the slider track should be highlighted or not |
| data-mini | true | false | Specifies whether the slider should be of small or regular size |
| data-role | none | Prevents jQuery Mobile to style slider controls as buttons |
| data-theme | letter (a-z) | Specifies the theme color of the slider control (the input, handle and track) |
| data-track-theme | letter (a-z) | Specifies the theme color of the slider track |