Button Widgetversion added: 1.0
Description: Creates a button widget
Buttons
Buttons are coded with standard HTML input
elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device.
Form buttons
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 button plugin on any selector, just like any jQuery plugin:
$( "[type='submit']" ).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">
Providing pre-rendered markup
You can improve the load time of your page by providing the markup that the button widget would normally create during its initialization.
By providing this markup yourself, and by indicating that you have done so by setting the attribute data-enhanced="true"
, you instruct the button widget to skip these DOM manipulations during instantiation and to assume that the required DOM structure is already present.
When you provide such pre-rendered markup you must also set all the classes that the framework would normally set, and you must also set all data attributes whose values differ from the default to indicate that the pre-rendered markup reflects the non-default value of the corresponding widget option.
The button widget adds a wrapper div
around the input
.
In the example below, pre-rendered markup for a button is provided. The attribute 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.
<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>
Options
corners
true
This option is also exposed as a data attribute: data-corners="false"
.
Initialize the button with the corners
option specified:
$( ".selector" ).button({ corners: false });
Get or set the corners
option, after initialization:
// Getter var corners = $( ".selector" ).button( "option", "corners" ); // Setter $( ".selector" ).button( "option", "corners", false );
disabled
false
true
. This option is also exposed as a data attribute: data-disabled="true"
.
Initialize the button with the disabled
option specified:
$( ".selector" ).button({ disabled: true });
Get or set the disabled
option, after initialization:
// Getter var disabled = $( ".selector" ).button( "option", "disabled" ); // Setter $( ".selector" ).button( "option", "disabled", true );
enhanced
false
This option is also exposed as a data attribute: data-enhanced="true"
.
Initialize the button with the enhanced
option specified:
$( ".selector" ).button({ enhanced: true });
Get or set the enhanced
option, after initialization:
// Getter var enhanced = $( ".selector" ).button( "option", "enhanced" ); // Setter $( ".selector" ).button( "option", "enhanced", true );
icon
null
The .buttonMarkup() documentation contains a reference of all the icons available in the default theme.
This option is also exposed as a data attribute: data-icon="star"
.
Initialize the button with the icon
option specified:
$( ".selector" ).button({ icon: "star" });
Get or set the icon
option, after initialization:
// Getter var icon = $( ".selector" ).button( "option", "icon" ); // Setter $( ".selector" ).button( "option", "icon", "star" );
iconpos
"left"
This option is also exposed as a data attribute: data-iconpos="right"
.
iconshadow
false
Applies the theme shadow to the button's icon if set to true.
This option is also exposed as a data attribute: data-iconshadow="true"
.
initSelector
See below
The default initSelector
for the button widget is:
"input[type='button'], input[type='submit'], input[type='reset']"
Note: This option is deprecated in 1.4.0 and will be removed in 1.5.0.
As of jQuery Mobile 1.4.0, the initSelector
is no longer a widget option. Instead, it is declared directly on the widget prototype. Thus, you may specify a custom value by handling the mobileinit
event and overwriting the initSelector
on the prototype:
$( document ).on( "mobileinit", function() { $.mobile.button.prototype.initSelector = "div.custom"; });
Note: Remember to attach the mobileinit
handler after you have loaded jQuery, but before you load jQuery Mobile, because the event is triggered as part of jQuery Mobile's loading process.
The value of this option is a jQuery selector string. The framework selects elements based on the value of this option and instantiates button widgets on each of the resulting list of elements.
(version deprecated: 1.4.0)inline
null (false)
true
, this will make the button act like an inline button so the width is determined by the button's text. By default, this is null (false) so the button is full width, regardless of the feedback content. Possible values: true, false. This option is also exposed as a data attribute: data-inline="true"
.
mini
null (false)
true
, this will display a more compact version of the button that uses less vertical height by applying the ui-mini
class to the outermost element of the button widget. This option is also exposed as a data attribute: data-mini="true"
.
shadow
true
This option is also exposed as a data attribute: data-shadow="false"
.
theme
null, inherited from parent
Possible values: swatch letter (a-z).
This option is also exposed as a data attribute: data-theme="b"
.
Initialize the button with the theme
option specified:
$( ".selector" ).button({ theme: "b" });
Get or set the theme
option, after initialization:
// Getter var theme = $( ".selector" ).button( "option", "theme" ); // Setter $( ".selector" ).button( "option", "theme", "b" );
wrapperClass
null
This option is also exposed as a data attribute: data-wrapper-class="custom-class"
.
Methods
destroy()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the destroy method:
$( ".selector" ).button( "destroy" );
disable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the disable method:
$( ".selector" ).button( "disable" );
enable()Returns: jQuery (plugin only)
- This method does not accept any arguments.
Invoke the enable method:
$( ".selector" ).button( "enable" );
option( optionName )Returns: Object
optionName
.- optionNameType: StringThe name of the option to get.
Invoke the method:
var isDisabled = $( ".selector" ).button( "option", "disabled" );
option()Returns: PlainObject
- This signature does not accept any arguments.
Invoke the method:
var options = $( ".selector" ).button( "option" );
option( optionName, value )Returns: jQuery (plugin only)
optionName
.- optionNameType: StringThe name of the option to set.
- valueType: ObjectA value to set for the option.
Invoke the method:
$( ".selector" ).button( "option", "disabled", true );
option( options )Returns: jQuery (plugin only)
- optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
$( ".selector" ).button( "option", { disabled: true } );
refresh()Returns: jQuery (plugin only)
If you manipulate a form button via JavaScript, you must call the refresh method on it to update the visual styling.
$( "[type='submit']" ).button( "refresh" );
- This method does not accept any arguments.
Invoke the refresh method:
$( ".selector" ).button( "refresh" );
Events
create( event, ui )Type: buttoncreate
Note: The ui
object is empty but included for consistency with other events.
Initialize the button with the create callback specified:
$( ".selector" ).button({ create: function( event, ui ) {} });
Bind an event listener to the buttoncreate event:
$( ".selector" ).on( "buttoncreate", function( event, ui ) {} );
Example:
A basic example of a button
<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>button demo</title> <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css"> <script src="//code.jquery.com/jquery-1.10.2.min.js"></script> <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script> </head> <body> <div data-role="page" id="page1"> <div data-role="header"> <h1>jQuery Mobile Example</h1> </div> <div role="main" class="ui-content"> <form action="#" method="get"> <input type="submit" value="Input Button"></input> </form> </div> </div> </body> </html>