jQuery Mobile Data Attribute

jQuery Data Attributes

jQuery Mobile uses HTML5 data-* attributes to create a "touch-friendly" and aesthetically pleasing appearance for mobile devices.

In the following reference list, the bold values specify the default values.

Button

Hyperlinks with data-role="button". Button elements, links, and input fields in the toolbar are automatically styled as buttons, so there is no need for data-role="button".

Data Attributes Value Description
data-corners true | false Specify whether the button has rounded corners.
All <select> elements. They will be automatically styled as buttons and do not require date-role. data-icon Specify the button icon. The default is without an icon.
Specifies the icon for the select element. The default is "arrow-d". data-iconpos Specifies the position of the icon. It can be left | right | top | bottom | notext.
data-iconshadow true | false Specify whether the button icon has a shadow.
data-inline true | false Specify whether the button is inline.
data-mini true | false Specify whether the button is small or of regular size.
data-shadow true | false Specify whether the button has a shadow.
data-theme letter (a-z) Specify the theme color of the button.

Tip:If you need to combine multiple buttons, use a container with attributes data-role="controlgroup" and data-type="horizontal|vertical" to specify whether the buttons are combined horizontally or vertically.

Checkbox

Label and 'input' with 'type="checkbox"' are paired. They will be automatically set to button style without 'data-role'.

Data Attributes Value Description
data-mini true | false Specify whether the checkboxes are small or regular size.
data-role none Prevent jQuery Mobile from setting the checkboxes to button style.
data-theme letter (a-z) Specify the theme color of the checkboxes.

Tip:To combine multiple checkboxes, use 'data-role="controlgroup"' and 'data-type="horizontal|vertical"' to specify horizontal or vertical combination of checkboxes.

Collapsible

Title element, followed by any HTML markup within a container with attribute 'data-role="collapsible"'.

Data Attributes Value Description
data-collapsed true | false Specify whether the content should be closed or expanded.
data-collapsed-icon data-icon Specify the icon of the collapsible button. The default is 'plus'.
data-content-theme letter (a-z) Specify the theme color of the collapsible content. It will also add rounded corners to the collapsible content.
data-expanded-icon data-icon Specify the icon of the collapsible button when the content is expanded. The default is 'minus'.
Specifies the icon for the select element. The default is "arrow-d". left | right | top | bottom Specifies the position of the icon. It can be left | right | top | bottom | notext.
data-inset true | false Specify whether the collapsible button has rounded corners and margin styles.
data-mini true | false Specify whether the collapsible button is small or regular size.
data-theme letter (a-z) Specify the theme color of the collapsible button.

Collapsible Set

Collapsible content block within a container with attribute 'data-role="collapsible-set"'.

Data Attributes Value Description
data-collapsed-icon data-icon Specify the icon of the collapsible button. The default is 'plus'.
data-content-theme letter (a-z) Specify the theme color of the collapsible content.
data-expanded-icon data-icon Specify the icon of the collapsible button when the content is expanded. The default is 'minus'.
Specifies the icon for the select element. The default is "arrow-d". data-iconpos Specifies the position of the icon. It can be left | right | top | bottom | notext.
data-inset true | false Specify whether the collapsibles have rounded corners and margin styles.
data-mini true | false Specify whether the collapsible button is small or regular size.
data-theme letter (a-z) Specify the theme color of the collapsible set.

Content

Container with attribute 'data-role="content"'.

Data Attributes Value Description
data-theme letter (a-z) Specify the theme color of the content. The default is 'c'.

Controlgroup

Container with attribute 'data-role="controlgroup"' or '<div>' or '<fieldset>'. Combine multiple button-style inputs of a single type (based on link buttons, radio buttons, checkboxes, select menus).

Data Attributes Value Description
data-mini true | false Specify whether the combination is small or regular size.
data-type horizontal | vertical Specify whether the combination is horizontally or vertically displayed.

Dialog

Container with attribute 'data-role="dialog"' or link with attribute 'data-rel="dialog"'.

Data Attributes Value Description
data-close-btn-text sometext Specify the text for the close button only used in dialogues.
data-dom-cache true | false Specify whether to clear the jQuery DOM cache for individual pages (if set to true, it is necessary to manage the DOM and conduct comprehensive testing on all mobile devices).
data-overlay-theme letter (a-z) Specify the overlay (background) color of the dialog page.
data-theme letter (a-z) Specify the theme color of the dialog page.
data-title sometext Specify the title of the dialog page.

Enhancement

Container with attributes data-enhance="false" or data-ajax="false".

Data Attributes Value Description
data-enhance true | false If set to "true" (default), jQuery Mobile will automatically add styles to the page to make it more suitable for mobile devices. If set to "false", the framework will not set the page's styles.
data-ajax true | false Specify whether the page is loaded via AJAX.

Note:data-enhance="false", for example combined with $.mobile.ignoreContentEnabled=true, to prevent jQuery Mobile from automatically adding page styles.

When $.mobile.ignoreContentEnabled is set to true, any links or form elements within containers with data-ajax="false" will be ignored by the framework's navigation feature.

Fieldcontainer

Container wrapping the label/form elements with data-role="fieldcontain".

Fixed Toolbar

Container with attributes data-role="header" or data-role="footer" and data-position="fixed".

Data Attributes Value Description
data-disable-page-zoom true | false Specify whether the user can zoom the page.
data-fullscreen true | false Specify whether the toolbar should always be at the top and/or bottom.
data-tap-toggle true | false Specify whether the user can toggle the visibility of the toolbar by tapping/clicking.
data-transition slide | fade | none Specify the transition effect when a tap/click occurs.
data-update-page-padding true | false Specify that the page's top and bottom padding should be updated when resize, transition, or "updatelayout" events occur (jQuery Mobile always updates the padding when the "pageshow" event occurs).
data-visible-on-page-show true | false Specify the visibility of the toolbar when the parent page is displayed.

Flip Toggle Switch

A <select> element with data-role="slider" attribute and two <option> elements.

Data Attributes Value Description
data-mini true | false Specify whether the switch is small or regular size.
data-role none Prevent jQuery Mobile from setting the toggle switch to button style.
data-theme letter (a-z) Specify the theme color of the toggle switch.
data-track-theme letter (a-z) Specify the theme color of the track.

Footer

Container with data-role="footer" attribute.

Data Attributes Value Description
data-id sometext Specify a unique ID. It is required for persistent footers.
data-position inline | fixed Specify whether the footer is in-line with the page content or remains at the bottom.
data-fullscreen true | false Specify whether the page footer is always at the bottom and covers the page content (slightly see-through).
data-theme letter (a-z) Specify the theme color of the page footer. The default is "a".

Note:To enable fullscreen positioning, use data-position="fixed" and then add the data-fullscreen attribute to the element.

Header

Container for data-role="header".

Data Attributes Value Description
data-id sometext Specify a unique ID. It is required for persistent headers.
data-position inline | fixed Specify whether the page header is in-line with the page content or remains at the top.
data-fullscreen true | false Specify whether the page is always at the top and covers the page content (slightly see-through).
data-theme letter (a-z) Specify the theme color of the page header. The default is "a".

Note:To enable fullscreen positioning, use data-position="fixed" and then add the data-fullscreen attribute to the element.

Link

All links, including links with data-role="button" and form submit buttons.

Data Attributes Value Description
data-ajax true | false Specify whether to load the page via AJAX to improve user experience and transitions. If set to false, jQuery Mobile will make a regular page request.
data-direction reverse Reverse transition animation (only for pages or dialogs)
data-dom-cache true | false Specify whether to clear the jQuery DOM cache of individual pages (if set to true, then you need to pay attention to the management of DOM and comprehensively test all mobile devices).
data-prefetch true | false Specify whether to prefetch the page into the DOM to make it available when the user accesses it.
data-rel back | dialog | external | popup Specify the options related to how links behave. Back - Moves one step back in the history record. Dialog - Opens the page as a dialog without recording in the history. External - Links to another domain. opens - Opens a popup window.
data-transition fade | flip | flow | pop | slide | slidedown | slidefade | slideup | turn | none Specify how to transition from one page to the next. Refer to jQuery Mobile transitions.
data-position-to origin | jQuery selector | window Specify the position of the pop-up. Origin - Default. It pops up on the link it opens. jQuery selector - Pop up on the specified element. Window - Pop up in the middle of the window screen.

List

The <ol> or <ul> with the attribute data-role="listview".

Data Attributes Value Description
data-autodividers true | false Specify whether to automatically separate list items.
data-count-theme letter (a-z) Specify the theme color of the bubble count. The default is "c".
data-divider-theme letter (a-z) Specify the theme color of the list separator. The default is "b".
data-filter true | false Specify whether to add a search box to the list.
data-filter-placeholder sometext Specify the text in the search box. The default is "Filter items...".
data-filter-theme letter (a-z) Specify the theme color of the search filter. The default is "c".
All <select> elements. They will be automatically styled as buttons and do not require date-role. data-icon Specify the icon of the list.
data-inset true | false Specify whether to add rounded corners and margin styles to the list.
data-split-icon data-icon Specify the icon of the split button. The default is "arrow-r".
data-split-theme letter (a-z) Specify the theme color of the split button. The default is "b".
data-theme letter (a-z) Specify the theme color of the list.

List item

The <li> inside the <ol> or <ul> with the attribute data-role="listview".

Data Attributes Value Description
data-filtertext sometext Specify the text to be searched when filtering elements. This text will be searched instead of the actual text of the list item.
All <select> elements. They will be automatically styled as buttons and do not require date-role. data-icon Specify the icon of the list item.
data-role list-divider Specify the separator of the list item.
data-theme letter (a-z) Specify the theme color of the list item.

Note:The data-icon attribute is only applicable to list items containing links.

Navbar

The <li> element inside the container with the attribute data-role="navbar".

Data Attributes Value Description
All <select> elements. They will be automatically styled as buttons and do not require date-role. data-icon Specify the icon of the list item.
Specifies the icon for the select element. The default is "arrow-d". data-iconpos Specifies the position of the icon. It can be left | right | top | bottom | notext.

Tip:The navigation bar inherits the theme-swatch from its parent container. It is not possible to set the data-theme attribute to the navigation bar. The data-theme attribute can be set separately for each link in the navbar.

Page

Container with the attribute data-role="page".

Data Attributes Value Description
data-add-back-btn true | false Automatically add a back button, only for the header.
data-back-btn-text sometext Specify the text of the back button.
data-back-btn-theme letter (a-z) Specify the theme color of the back button.
data-close-btn-text letter (a-z) Specify the text of the close button on the dialog.
data-dom-cache true | false Specify whether to clear the jQuery DOM cache of individual pages (if set to true, then you need to pay attention to the management of DOM and comprehensively test all mobile devices).
data-overlay-theme letter (a-z) Specify the overlay (background) color of the dialog page.
data-theme letter (a-z) Specify the theme color of the page. Default is "c".
data-title sometext Specify the page title.
data-url url This value is used to update the URL, not to request a page.

Popup

Container with data-role="popup" attribute.

Data Attributes Value Description
data-corners true | false Specify whether the pop-up has rounded corners.
data-overlay-theme letter (a-z) Specify the overlay (background) color of the pop-up. Default is transparent background (none).
data-shadow true | false Specify whether the pop-up has a shadow.
data-theme letter (a-z) Specify the theme color of the pop-up. Default is inherited, "none" sets to transparent.
data-tolerance 30, 15, 30, 15 Specify the distance from the window edge (top, right, bottom, left).

Anchor with data-rel="popup" attribute:

Data Attributes Value Description
data-position-to origin | jQuery selector | window Specify the position of the pop-up. Origin - Default. The pop-up is located on the link that opens it. jQuery selector - The pop-up is located on the specified element. Window - The pop-up is located at the center of the window screen.
data-rel popup Used to open pop-ups.
data-transition fade | flip | flow | pop | slide | slidedown | slidefade | slideup | turn | none Specify how to transition from one page to the next. Refer to jQuery Mobile transitions.

Radio Button

label corresponds to the input with type="radio" and will be automatically set to button style without data-role.

Data Attributes Value Description
data-mini true | false Specify whether the button is small or of regular size.
data-role none Place jQuery Mobile to set the radio buttons to the enhanced buttons style.
data-theme letter (a-z) Specify the theme color of the radio buttons.

Tip:To combine multiple radio buttons, use data-role="controlgroup" and data-type="horizontal|vertical" to specify whether to combine buttons horizontally or vertically.

Select

Select

Data Attributes Value Description
All <select> elements. They will be automatically styled as buttons and do not require date-role. data-icon Icons Reference
Specifies the icon for the select element. The default is "arrow-d". data-iconpos Specifies the position of the icon. It can be left | right | top | bottom | notext.
data-inline true | false Specifies whether the select element is inline.
data-mini true | false Specifies whether the select element is small or standard size.
data-native-menu true | false If set to false, jQuery's own custom select menu will be used (it is recommended to use it if you want the select menu to have a consistent appearance on all mobile devices).
data-overlay-theme letter (a-z) Specifies the theme color for jQuery custom select menu (to be used with data-native-menu="false").
data-placeholder true | false Can be set on the non-native <option> element of select.
data-role none Styles the select element as a button when placed within jQuery Mobile.
data-theme letter (a-z) Specifies the theme color for the select element.

Tip:If you need to combine multiple select elements, use data-role="controlgroup" and data-type="horizontal|vertical" to specify whether to combine the element horizontally or vertically.

Slider

input element with type="range". It will be automatically styled as a button and does not require data-role.

Data Attributes Value Description
data-highlight true | false Specifies whether the slider track should be highlighted.
data-mini true | false Specifies whether the slider is small or standard size.
data-role none Styles the slider set button when placed within jQuery Mobile.
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 & Textarea

An input element or textarea element with type="text|search|etc.". It will be automatically styled and does not require data-role.

Data Attributes Value Description
data-mini true | false Specify whether the input element is small or regular size.
data-role none Place jQuery Mobile to set the style of input/textarea as a button.
data-theme letter (a-z) Define the theme color of the input field.