.buttonMarkup()

Transition to class-based styling

• When using icons, you must always specify an icon position class along with the icon class, because there is no longer a default icon position. In the example below the class ui-btn-icon-left is added to make sure the icon (ui-icon-arrow-r) will be displayed.

  <a href="http://example.com/" class="ui-btn ui-icon-arrow-r ui-btn-icon-left ui-corner-all ui-shadow ui-btn-inline">Example</a>

• Although the style-related data attributes are deprecated, the data attributes related to linking behavior remain unchanged. In the example below the button is styled using classes, but the data attributes related to linking are retained.

  <a href="/" data-rel="external" class="ui-btn ui-corner-all ui-shadow ui-btn-inline ui-icon-home ui-btn-icon-left">Home</a>

• We do not recommend mixing styling based on data attributes and class-based styling during the deprecation period.

Button markup

You can use .buttonMarkup() to style any element as a button that is attractive and useable on a mobile device. It is a convenience function that allows you to manipulate the classes related to button styling. For each element in the set of matched elements this function converts the options parameter to a list of classes to be applied to the element, while respecting the element's existing classes that are not related to button styling. You may also set the parameter overwriteClasses to true for performance reasons. When overwriteClasses is set to true the function discards existing classes and applies the classes corresponding to the options provided.

Autoinitialization

The framework will automatically apply button styling to anchors that have the attribute data-role="button" as well as button elements, anchors contained directly in bars and controlgroup widgets. You can specify button styling options via data attributes that you add to the anchor or button element. The data attribute corresponding to each .buttonMarkup() option is documented in the options of .buttonMarkup(). The example below shows the markup needed for an anchor-based button.

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

Produces this anchor-based button:

Button based button:

.buttonMarkup() also automatically enhances button elements such as the one below:

<button>Button element</button>

Disabled appearance

You can style an anchor as disabled by adding the class ui-state-disabled.

Note: It is not inherently possible to "disable" anchors. The class ui-state-disabled merely adds styling to make the anchor look disabled. It does not provide the same level of functionality as the disabled attribute of a form button. It may still be possible to follow the anchor using navigation methods that do not involve the pointing device.

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

Produces an anchor-based button styled as disabled:

In the case of button elements, you should apply the ui-state-disabled class when you set the button element's disabled attribute:

// Toggle the class ui-state-disabled in conjunction with modifying the value
// of the button element's "disabled" property
$( "button#myButton" )
  .prop( "disabled", isDisabled )
  .toggleClass( "ui-state-disabled", isDisabled );

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.

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</a>

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

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:

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

Icon set

The following data-icon attributes can be referenced to create the icons shown below:

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:

<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:after class to specify the icon background source. The framework contains an inline (data URI) SVG test and adds class ui-nosvg to the html element if this is not supported. If you are using SVG icons you can use this class to provide a fallback to external PNG icons.

.ui-icon-myapp-email:after {
  background-image: url('data:image/svg+xml;...');
}
.ui-nosvg .ui-icon-myapp-email:after {
  background-image: url( "app-icon-email.png" );
}

Icons and themes

The semi-transparent black circle behind the white icon ensures good contrast on any background color so it works well with the jQuery Mobile theming system. Here are examples of the same icons sitting on top of a range of different color swatches with themed buttons.

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 button-styled elements

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" will be automatically assigned the button theme of "a". 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="b">Swatch b</a>

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

Theme variations

corners true

Adds the class ui-corner-all when true and removes it when false. This gives the button-styled element rounded corners.

This option is also exposed as a data-attribute: data-corners="false"

Adds an icon class by prefixing the value with the string "ui-icon-" and an icon position class based on the value of the iconpos option.

For example, if the value is "arrow-r" and the value of the iconpos option is "left", then .buttonMarkup() will add the classes ui-icon-arrow-r and ui-btn-icon-left to each of the set of matched elements.

This option is also exposed as a data-attribute: data-icon="arrow-r"

Adds an icon position class by prefixing the value with the string "ui-btn-icon-" when the button-styled element has an icon.

For example, if the value is "right" and the button-styled element has an icon, then the class ui-btn-icon-right will be added to each of the set of matched elements.

This option is also exposed as a data-attribute: data-iconpos="right"

This option is deprecated in 1.4.0 and will be removed in 1.5.0.

Adds the class ui-shadow-icon to each of the set of matched elements when set to true and the button-styled element has an icon.

This option is also exposed as a data-attribute: data-iconshadow="true"

(version deprecated: 1.4.0)

Adds the class ui-btn-inline to each of the set of matched elements when set to true.

This option is also exposed as a data-attribute: data-inline="true"

Adds the class ui-mini to each of the set of matched elements when set to true.

This option is also exposed as a data-attribute: data-mini="true"

Adds the class ui-shadow to each of the set of matched elements when set to true.

This option is also exposed as a data-attribute: data-shadow="false"

The value is a letter a-z identifying one of the color swatches in the current theme, or null.

This option adds a class constructed by appending the string "ui-btn-" to the value to each of the set of matched elements. If set to null, no class is added, and the swatch is inherited from the element's parent.

For example, a value of "b" will cause the class ui-btn-b to be added to each of the set of matched elements.

This option is also exposed as a data-attribute: data-theme="b"

When set to true, .buttonMarkup() discards all classes on each of the set of matched elements and adds classes based on the values passed into the options argument. You can use this feature to increase performance in situations where the element you wish to enhance does not have any classes other than the button styling classes added by .buttonMarkup().

Conversely, when set to false, .buttonMarkup() first parses the existing classes found on each of the set of matched elements and computes a set of existing options based on the presence or absence of classes related to button styling already present. It separately records any classes unrelated to button styling. It then merges the options specified in the options parameter with the computed options such that the options passed in take precedence, and calculates a list of classes that must be present for those options to be expressed in the element's styling. It then re-applies the classes unrelated to button styling as well as the classes that reflect the new set of options. This means that calling .buttonMarkup() on the same element multiple times will have the expected effect:

// Initially corners are turned off
$( "#myAnchor" ).buttonMarkup({ corners: false });
 
// Later on we turn off shadow - the lack of corners is retained
$( "#myAnchor" ).buttonMarkup({ shadow: false });
 
// Later still we turn corners back on - the lack of shadow is retained
$( "#myAnchor" ).buttonMarkup({ corners: true });