.buttonMarkup( options, overwriteClasses )Returns: jQueryversion deprecated: 1.4.0
Description: Adds button styling to an element
button
or a
elements by simply adding classes.Transition to class-based styling
Keeping in mind the followings will make it easy for you to transition from the button styling based on data attributes to the class-based process:- 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.1<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.
1
<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.
1
|
|
Produces this anchor-based button:
Button based button:
.buttonMarkup()
also automatically enhances button
elements such as the one below:
1
|
|
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.
1
|
|
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:
1
2
3
4
5
|
|
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.
1
2
|
|
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.
1
|
|
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:
1
|
|
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:
1
|
|
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"
:
1
|
|
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.
1
2
3
4
5
6
|
|
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.
1
2
3
4
5
|
|
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.
1
|
|
Here are 2 buttons with icons that have a different swatch letter assigned via the data-theme
attribute.