Button Widget

Buttons are coded with standard HTML anchor and input elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device. Use anchor links (a elements) to mark up navigation buttons, and input or button elements for form submission.

Styling links as buttons

In the main content block of a page, you can style any anchor link as a button by adding the data-role="button" attribute. The framework will enhance the link with markup and classes to style the link as a button. For example, this markup:

<a href="index.html" data-role="button">Link button</a>

Produces this link-based button:

Note: Links styled like buttons have all the same visual options as true form-based buttons below, but there are a few important differences. Link-based buttons aren't part of the button plugin and only just use the underlying buttonMarkup plugin to generate the button styles so the form button methods (enable, disable, refresh) aren't supported. If you need to disable a link-based button (or any element), it's possible to apply the disabled class ui-disabled yourself with JavaScript to achieve the same effect.

<a href="index.html" data-role="button" class="ui-disabled">Link button</a>

Produces this disabled link-based button:

Mini version

For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the button to create a mini version.

<a href="index.html" data-role="button" data-mini="true">Link button&lt;/a>

This will produce a button that is not as tall as the standard version and has a smaller text size.

Form buttons

For ease of styling, the framework automatically converts any button or input element with a type of submit, reset, or button into a custom styled button - there is no need to add the data-role="button" attribute. However, if needed, you can directly call the button plugin on any selector, just like any jQuery plugin:

$( "[type='submit']" ).button();

Button based button:

<button>Button element</button>

Input type="button" based button:

<input type="button" value="Button">

Input type="submit" based button:

<input type="submit" value="Submit Button">

Input type="reset" based button:

<input type="reset" value="Reset Button">

Adding Icons to Buttons

The jQuery Mobile framework includes a selected set of icons most often needed for mobile apps. To minimize download size, jQuery Mobile includes a single white icon sprite, and automatically adds a semi-transparent black circle behind the icon to ensure that it has good contrast on any background color.

An icon can be added to a button by adding a data-icon attribute on the anchor specifying the icon to display. For example, the following markup:

<a href="index.html" data-role="button" data-icon="delete">Delete</a>

Icon set

The full list of data-icon attributes can found on the icons reference page

Icon positioning

By default, all icons in buttons are placed to the left of the button text.

This default may be overridden using the data-iconpos attribute to set the icon to the right, above (top) or below (bottom) the text. For example, the markup:

<a href="index.html" data-role="button" data-icon="delete" data-iconpos="right">Delete</a>

You can also create an icon-only button, by setting the data-iconpos attribute to notext. The button plugin will hide the text on-screen, but add it as a title attribute on the link to provide context for screen readers and devices that support tooltips. For example, replacing data-iconpos="right" on the previous example with data-iconpos="notext":

<a href="index.html" data-role="button" data-icon="delete" data-iconpos="notext">Delete</a>

Creates this icon-only button:

Mini & Inline

The mini and inline attributes can be added to produce more compact buttons:

Custom Icons

To use custom icons, specify a data-icon value that has a unique name like myapp-email and the button plugin will generate a class by prefixing ui-icon- to the data-icon value and apply it to the button: ui-icon-myapp-email.

You can then write a CSS rule in your stylesheet that targets the ui-icon-myapp-email class to specify the icon background source. To maintain visual consistency with the rest of the icons, create a white icon 18x18 pixels saved as a PNG-8 with alpha transparency.

In this example, we're just pointing to a standalone icon image, but you could just as easily use an icon sprite and specify the positioning instead, just like the icon sprite we use in the framework.

.ui-icon-myapp-email {
  background-image: url( "app-icon-email.png" );
}

This will create the standard resolution icon, but many devices now have very high resolution displays, like the retina display on the iPhone 4. To add a HD icon, create an icon that is 36x36 pixels (exactly double the 18 pixel size), and add second a rule that uses the -webkit-min-device-pixel-ratio: 2 media query to target a rule only to high resolution displays. Specify the background image for the HD icon file and set the background size to 18x18 pixels which will fit the 36 pixel icon into the same 18 pixel space. The media query block can wrap multiple icon rules:

@media only screen and (-webkit-min-device-pixel-ratio: 2) {
  .ui-icon-myapp-email {
    background-image: url( "app-icon-email-highres.png" );
    background-size: 18px 18px;
  }
  ...more HD icon rules go here...
}

Inline buttons

By default, all buttons in the body content are styled as block-level elements so they fill the width of the screen:

If you have multiple buttons that should sit side-by-side on the same line, add the data-inline="true" attribute to each button. This will style the buttons to be the width of their content and float the buttons so they sit on the same line.

<a href="index.html" data-role="button" data-inline="true">Cancel</a>
<a href="index.html" data-role="button" data-inline="true" data-theme="b">Save</a>

If you want buttons to sit side-by-side but stretch to fill the width of the screen, you can use the content column grids to put normal full-width buttons into 2- or 3-columns.

Icon example

Grouped buttons

Occasionally, you may want to visually group a set of buttons to form a single block that looks contained like a navigation component. To get this effect, wrap a set of buttons in a container with the data-role="controlgroup" attribute - the framework will create a vertical button group, remove all margins and drop shadows between the buttons, and only round the first and last buttons of the set to create the effect that they are grouped together.

<div data-role="controlgroup">
  <a href="index.html" data-role="button">Yes</a>
  <a href="index.html" data-role="button">No</a>
  <a href="index.html" data-role="button">Maybe</a>
</div>

By default, grouped buttons are presented as a vertical list:

By adding the data-type="horizontal" attribute to the controlgroup container, you can swap to a horizontal-style group that floats the buttons side-by-side and sets the width to only be large enough to fit the content. (Be aware that these will wrap to multiple lines if the number of buttons or the overall text length is too wide for the screen.)

Labels

Because the label element will be associated with each individual input or button and will be hidden for styling purposes, we recommend wrapping the buttons in a fieldset element that has a legend which acts as the combined label for the group. Using the label as a wrapper around an input prevents the framework from hiding it, so you have to use the for attribute to associate the label with the input.

Theming buttons

jQuery Mobile has a rich theming system that gives you full control of how buttons are styled. When a link is added to a container, it is automatically assigned a theme swatch letter that matches its parent bar or content box to visually integrate the button into the parent container, like a chameleon. So a button placed inside a content container with a theme of "a" (black in the default theme) will be automatically assigned the button theme of "a" (charcoal in the default theme). Here are examples of the button theme pairings in the default theme. All buttons have the same HTML markup:

Assigning theme swatches

Buttons can be manually assigned any of the button color swatches from the theme to add visual contrast with the container they sit inside by adding the data-theme attribute on the button markup and specifying a swatch letter.

<a href="index.html" data-role="button" data-theme="a">Swatch a</a>

Here are 5 buttons with icons that have a different swatch letter assigned via the data-theme attribute.

Theme variations