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.
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:
Buttons are coded with standard HTML input elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device.
-<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: - -
- -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.
For ease of styling, the framework automatically converts any 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
-<a href="index.html" data-role="button" data-mini="true">Link button</a>
+$( "[type='submit']" ).button();
This will produce a button that is not as tall as the standard version and has a smaller text size. - -
- -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:
Input type="button" based
-$( "[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" based
<input type="submit" value="Submit Button" />
Input type="reset" based button:
-
-<input type="reset" value="Reset Button" />
-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>
-The following data-icon attributes can be referenced to create the icons shown below:
-
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":
Input type="reset" based
-<a href="index.html" data-role="button" data-icon="delete" data-iconpos="notext">Delete</a>
+<input type="reset" value="Reset Button" />
Creates this icon-only button: -
- -The mini and inline attributes can be added to produce more compact buttons: -
- -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...
-}
-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.
- --
- -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.
+The div around the input.
In the example below, pre-rendered markup for a data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the wrapper element indicates that the "corners" widget option is to be false.
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 class="ui-btn ui-input-btn ui-shadow">
+ The Button
+ <input type="button" data-corners="false" data-enhanced="true" value="The Button"></input>
</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.)
-
- -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.
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: -
- -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.
-
-$( "[type='submit']" ).button( "enable" );
-
-$( "[type='submit']" ).button( "disable" );
-If you manipulate a form button via JavaScript, you must call the refresh method on it to update the visual styling.
+If you manipulate a form
$( "[type='submit']" ).button( "refresh" );
button or a elements by simply adding classes.
+
+ 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>
+
+<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>
+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.
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>
+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 );
+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.
+ +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. + +
+ +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>
+The following data-icon attributes can be referenced to create the icons shown below:
+
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: +
+ +The mini and inline attributes can be added to produce more compact buttons: +
+ +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" );
+}
+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.
+ ++
+ +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.)
+
+ +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.
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: +
+ +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.
+
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"
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"
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"
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"
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"
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"
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"
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"
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 });
+Checkboxes are used to provide a list of options where more than one can be selected. Traditional desktop checkboxes are not optimized for touch input so in jQuery Mobile, we style the label for the checkboxes so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.
Checkboxes are used to provide a list of options where more than one can be selected. Traditional desktop checkboxes are not optimized for touch input so in jQuery Mobile, we style the label for the checkboxes so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.
The checkbox controls below use standard input/label markup, but are styled to be more touch-friendly. The styled control you see is actually the label element, which sits over the real input, so if images fail to load, you'll still have a functional control. In most browsers, clicking the label automatically triggers a click on the input, but we've had to trigger the update manually for a few mobile browsers that don't do this natively. On the desktop, these controls are keyboard and screen-reader accessible.
-To create a single checkbox, add an input with a type="checkbox" attribute and a corresponding label. If the input isn’t wrapped in its corresponding label, be sure to set the for attribute of the label to match the id of the input so they are semantically associated.
To create a single checkbox, add an input with a type="checkbox" attribute and a corresponding label. If the input isn't wrapped in its corresponding label, be sure to set the for attribute of the label to match the id of the input so they are semantically associated.
<label><input type="checkbox" name="checkbox-0" /> I agree </label>
@@ -20,7 +20,7 @@
Mini version
- For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
+ For a more compact version that is useful in toolbars and tight spaces, add the data-mini="true" attribute to the element to create a mini version.
<input type="checkbox" name="checkbox-mini" id="checkbox-mini-1" class="custom" data-mini="true" />
@@ -32,10 +32,13 @@
Field containers & Legends
+ Optionally wrap the checkboxes in a container with class ui-field-contain to help visually group it in a longer form.
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
+
Because checkboxes use the label element for the text displayed next to the checkbox form element, we recommend wrapping the checkbox in a fieldset element that has a legend which acts as the title for the question. Add the data-role="controlgroup" attribute to the fieldset so it can be styled in a parallel way as text inputs, selects or other form elements.
-<div data-role="fieldcontain">
+<div class="ui-field-contain">
<fieldset data-role="controlgroup">
<legend>Agree to the terms:</legend>
<input type="checkbox" name="checkbox-2" id="checkbox-2" class="custom" />
@@ -47,7 +50,7 @@
Vertically grouped checkboxes
- Checkboxes can also be used for grouped button sets where more than one button can be selected at once, such as the bold, italic and underline button group seen in word processors. To make a horizontal button set, add the data-type="horizontal" to the fieldset.
+
Checkboxes can also be used for grouped button sets where more than one button can be selected at once, such as the bold, italic and underline button group seen in word processors. To make a horizontal button set, add the data-type="horizontal" to the fieldset.
@@ -57,11 +60,11 @@
The framework will float the labels so they sit side-by-side on a line, hide the checkbox icons and only round the left and right edges of the group.
Radio buttons
- Radio buttons are used to provide a list of options where only a single item can be selected. Traditional desktop radio buttons are not optimized for touch input so jQuery Mobile styles the label for the radio buttons so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.
+ Radio buttons are used to provide a list of options where only a single item can be selected. Traditional desktop radio buttons are not optimized for touch input so jQuery Mobile styles the label for the radio buttons so they are larger and look clickable. A custom set of icons are added to the label to provide additional visual feedback.
The radio button controls below use standard input/label markup, but are styled to be more touch-friendly. The styled control you see is actually the label element, which sits over the real input, so if images fail to load, you'll still have a functional control. In most browsers, clicking the label automatically triggers a click on the input, but we've had to trigger the update manually for a few mobile browsers that don't do this natively. On the desktop, these controls are keyboard and screen-reader accessible.
Vertically grouped radio buttons
-
+
To create a set of radio buttons, add an input with a type="radio" attribute and a corresponding label. Set the for attribute of the label to match the id of the input so they are semantically associated.
The label element is displayed next to the radio form element. Wrap the radio buttons in a fieldset element that has a legend which acts as the title for the question.
To visually integrate multiple radio buttons into a vertically grouped button set, the framework will automatically remove all margins between buttons and round only the top and bottom corners of the set if there is a data-role="controlgroup" attribute on the container.
@@ -108,10 +111,11 @@
Field containers
- Optionally wrap the radiobuttons in a container with the data-role="fieldcontain" attribute to help visually group it in a longer form.
+ Optionally wrap the radio buttons in a container with class ui-field-contain to help visually group it in a longer form.
+ Note: The data- attribute data-role="fieldcontain" is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class ui-field-contain instead.
-<div data-role="fieldcontain">
+<div class="ui-field-contain">
<fieldset data-role="controlgroup">
<legend>Choose a pet:</legend>
<input type="radio" name="radio-choice-2" id="radio-choice-21" value="choice-1" checked="checked" />
@@ -142,46 +146,50 @@
The labels float so they sit side-by-side on a line. The radio button icons are hidden and only the left and right edges of the group are rounded.
-
+
+ The checkboxradio widget wraps the input element in a div and prepends the label element to the div.
+ In the example below, pre-rendered markup for a checkbox is provided. The attribute data-corners="false" is explicitly specified, since the absence of the ui-corner-all class on the label element indicates that the value of the "corners" widget option is to be false.
+
+
+<div class="ui-checkbox">
+ <label for="my-checkbox" class="ui-btn ui-btn-inherit ui-btn-icon-left ui-checkbox-off">My Checkbox</label>
+ <input type="checkbox" id="my-checkbox" data-corners="false" data-enhanced="true"></input>
+</div>
+
+
+
+
If you manipulate a checkboxradio via JavaScript, you must call the refresh method on it to update the visual styling.