jQuery Mobile Data Attributes

jQuery Data Attributes

jQuery Mobile UsageHTML5 data-* Attributesto create a more touch-friendly and attractive appearance for mobile devices.

In the reference list below,values shown in boldare the default values.

Buttons

Deprecated after version 1.4. UseCSS classesinstead.Hyperlinks withdata-role="button"`data-role="button"`. Button elements, links in toolbars, and input fields are automatically rendered as buttons without needing to add `data-role="button"`.

Data Attributes Value Description
data-corners true | false Specifies whether the button has rounded corners
data-icon Icon Reference Specifies the icon for 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 has a shadow
data-inline true | false Specifies whether the button is inline
data-mini true | false Specifies whether the button is small or regular size
data-shadow true | false Specifies whether the button has a shadow
data-theme Letters (a-z) Specifies the theme color of the button

lamp To combine multiple buttons, use a container with `data-role="controlgroup"` and `data-type="horizontal|vertical"` to specify whether to group the buttons horizontally or vertically.

Checkboxes

withtype="checkbox"pairs of label and input. They are automatically rendered as buttons; data-role is not required.

Data Attributes Value Description
data-mini true | false Specifies whether the checkbox is small or regular size
data-role none Prevents jQuery Mobile from rendering the checkbox as a button
data-theme Letters (a-z) Specifies the theme color of the checkbox

lamp To combine multiple checkboxes, use a container with `data-role="controlgroup"` and `data-type="horizontal|vertical"` to specify whether to group the checkboxes horizontally or vertically.

Collapsible Blocks

In a container withdata-role="collapsible"`data-role="collapsible"`, a heading element followed by any HTML markup.

Data Attributes Value Description
data-collapsed true | false Specifies whether the content is collapsed or expanded
data-collapsed-icon Icon Reference Specifies the icon for the collapsible button. Default is "plus".
data-content-theme Letters (a-z) Specifies the theme color of the collapsible content. Whether to add 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 whether the collapsible button is rendered with rounded corners and margins
data-mini true | false Specifies whether the collapsible button is small or regular size
data-theme Letters (a-z) Specifies the theme color of the collapsible button

Collapsible Sets

In a container withdata-role="collapsible-set"`data-role="collapsible-set"`, collapsible content blocks.

Data Attributes Value Description
data-collapsed-icon Icon Reference Specifies the icon for the collapsible button. Default is "plus".
data-content-theme Letters (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 whether the collapsible blocks are rendered with rounded corners and margins
data-mini true | false Specifies whether the collapsible button is small or regular size
data-theme Letters (a-z) Specifies the theme color of the collapsible set

Content

Deprecated in version 1.4, no longer supported after version 1.5.Usedata-role="content"a container with `data-role="content"`.

Data Attributes Value Description
data-theme Letters (a-z) Specifies the theme color of the content.

Control Groups

withdata-role="controlgroup"`data-role="controlgroup"` `<div>` or `<fieldset>` container. 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 Attributes Value Description
data-mini true | false Specifies whether the control group is small or regular size
data-type horizontal | vertical Specifies whether the control group is displayed horizontally or vertically

Dialogs

withdata-role="dialog"`data-role="dialog"` container, or withdata-rel="dialog"`data-rel="dialog"` link.

Data Attributes 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 individual pages (if set to true, you must manage the DOM yourself and test on all mobile devices)
data-overlay-theme Letters (a-z) Specifies the mask (background) color of the dialog page
data-theme Letters (a-z) Specifies the theme color of the dialog page
data-title sometext Specifies the title of the dialog page

Enhancement

withdata-enhance="false"ordata-ajax="false"`data-enhance="false"` container.

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

Note:`data-enhance="false"` must be used together with `$.mobile.ignoreContentEnabled=true` to prevent jQuery Mobile from automatically enhancing the page.

When `$.mobile.ignoreContentEnabled` is set to true, any links or form elements inside a `data-ajax="false"` container will be ignored by the framework's navigation functionality.

Field Containers

Deprecated after version 1.4, no longer supported after version 1.5. Use `class="ui-fieldcontain"` instead.Wraps label/form element pairs, withdata-role="fieldcontain"`data-role="fieldcontain"` container.

Fixed Toolbars

withdata-role="header"ordata-role="footer", and withdata-position="fixed"`data-position="fixed"` attribute container.

Data Attributes Value Description
data-disable-page-zoom true | false Specifies whether the user can zoom the page
data-fullscreen true | false Specifies whether the toolbar is always fixed at the top or bottom
data-tap-toggle true | false Specifies whether the user can toggle the visibility of the toolbar by clicking
data-transition slide | fade | none Specifies the toggle effect when the click occurs
data-update-page-padding true | false Specifies whether the top and bottom padding of the page is updated on resize, transition, and "updatelayout" events (jQuery Mobile always updates padding on the "pageshow" event)
data-visible-on-page-show true | false Specifies the visibility of the toolbar when the parent page is shown

Flip Toggle Switches

One withdata-role="slider"the `<select>` element and two `<option>` elements.

Data Attributes Value Description
data-mini true | false Specifies whether the switch is small or regular size
data-role none Prevents jQuery Mobile from rendering the toggle switch as a button
data-theme Letters (a-z) Specifies the theme color of the toggle switch
data-track-theme Letters (a-z) Specifies the theme color of the track

Footer Bar

withdata-role="footer"container.

Data-attribute Value Description
data-id sometext Specifies a unique ID. Required for persistent footers.
data-position inline | fixed Specifies whether the footer is inline with the page content or remains fixed at the bottom.
data-fullscreen true | false Specifies whether the footer 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. Default is "a".

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

Header Bar

withdata-role="header"container.

Data-attribute Value Description
data-id sometext Specifies a unique ID. Required for persistent headers.
data-position inline | fixed Specifies whether the header is inline with the page content or remains fixed at the top.
data-fullscreen true | false Specifies whether the header 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. 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 submit buttons.

Data-attribute Value Description
data-ajax true | false Specifies whether to load pages via ajax to improve 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 prefetch pages into the DOM so that 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 history. Dialog - opens the link as a dialog, not saved in history. External - used for linking to another domain. Popup - opens a popup.
data-transition fade | flip | flow | pop | slide | slidedown | slidefade | slideup | turn | none Specifies the effect when switching from one page to the next. Check out ourjQuery Mobile page transitionssection.
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 the specified element. Window - Positions the popup in the center of the window screen.

Lists

withdata-role="listview"the <ol> or <ul>.

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 of the count bubble.
data-divider-theme Letter (a-z) Specifies the theme color of list dividers.
data-filter true | false Specifies whether to add a search box to the list.
data-filter-placeholder sometext Deprecated after 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 Icon reference Specifies the icon of the list.
data-inset true | false Specifies whether the list is rendered with rounded corners and margins.
data-split-icon Icon 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 Items

withdata-role="listview"the <li> inside an <ol> or <ul>.

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 Specifies the list item icon.
data-role list-divider Specifies the list item divider.
data-theme Letter (a-z) Specifies the theme color of the list item.

Note:The data-icon attribute only works on list items with links.

Navbars

withdata-role="navbar"the <li> elements inside a container.

Data-attribute Value Description
data-icon Icon reference Specifies the icon for the list item.
data-iconpos left | right | top | bottom | notext Specifies the position of the icon.

lamp Navbars inherit the theme swatch from their parent container. It is not possible to set the data-theme attribute for the navbar. You can set the data-theme attribute individually for each link in the navbar.

Pages

withdata-role="page"the container.

Data-attribute Value Description
data-add-back-btn true | false Automatically add a back button, header bars only.
data-back-btn-text sometext Specifies the text for the back button.
data-back-btn-theme Letter (a-z) Specifies the theme color of the back button.
data-close-btn-text Letter (a-z) Specifies the 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 overlay (background) color of the dialog page.
data-theme Letter (a-z) Specifies the theme color of the page.
data-title sometext Specifies the page title.
data-url url Updates the URL value, rather than the URL used to request the page.

Popups

withdata-role="popup"the container.

Data-attribute Value Description
data-corners true | false Specifies whether the popup is rounded.
data-overlay-theme Letter (a-z) Specifies the overlay (background) color of the popup. Default is transparent background (none).
data-shadow true | false Specifies whether the popup has a shadow.
data-theme Letter (a-z) Specifies the theme color of the popup. 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).

withdata-rel="popup"the anchor:

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 the 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 when switching from one page to the next. Check out ourjQuery Mobile page transitionssection.

Radio Buttons

withtype="radio"the paired label and input. 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 as an enhanced button, making the element display in its native HTML state.
data-theme Letter (a-z) Specifies the theme color of the radio button.

lamp 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.

Select

All<select>elements. These are automatically rendered as button styles, data-role is not required.

Data-attribute Value Description
data-icon Icon reference Specifies the icon for 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 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 built-in custom select menu (recommended if you want the select menu to look the same on all mobile devices).
data-overlay-theme Letter (a-z) Specifies the theme color of jQuery's built-in custom select menu (used with data-native-menu="false").
data-placeholder true | false Can be set on an <option> element of a non-native select menu.
data-role none Prevents jQuery Mobile from rendering the select element as a button style.
data-theme Letter (a-z) Specifies the theme color of the select element.

lamp To combine 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.

Slider

withtype="range"input boxes. These are automatically rendered as button styles, date-role is not required.

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 of the slider control (input, handle, and track)
data-track-theme Letter (a-z) Specifies the theme color of the slider track

Text Inputs & Textareas

withtype="text|search|etc."input ortextarea element. These are automatically rendered as button styles, date-role is not required.

Data-attribute Value Description
data-mini true | false Specifies whether the input is small or regular size
data-role none Prevents jQuery Mobile from rendering input boxes/text areas as button styles
data-theme Letter (a-z) Specifies the theme color of the input field


Other Extensions