Latest web development tutorials
 

jQuery Mobile Data Attributes


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