Button Widget

Categories: Widgets

Button Widgetversion added: 1.0

Description: Creates a button widget

QuickNavExamples

Options

Methods

Events

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:

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

Input type="button" based button:

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

Input type="submit" based button:

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

Input type="reset" based button:

1
 
<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.

1
2
3
4
 
<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

cornersType: Boolean

Default: true
Applies the theme button border-radius if set to true.

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

Code examples:

Initialize the button with the corners option specified:

1
 
$( ".selector" ).button({ corners: false });

Get or set the corners option, after initialization:

1
2
3
4
5
 
// getter
var corners = $( ".selector" ).button( "option", "corners" );
 
// setter
$( ".selector" ).button( "option", "corners", false );

disabledType: Boolean

Default: false
Disables the button if set to true.

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

Code examples:

Initialize the button with the disabled option specified:

1
 
$( ".selector" ).button({ disabled: true });

Get or set the disabled option, after initialization:

1
2
3
4
5
 
// getter
var disabled = $( ".selector" ).button( "option", "disabled" );
 
// setter
$( ".selector" ).button( "option", "disabled", true );

enhancedType: Boolean

Default: false
Indicates that the markup necessary for a button widget has been provided as part of the original markup.

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

Code examples:

Initialize the button with the enhanced option specified:

1
 
$( ".selector" ).button({ enhanced: true });

Get or set the enhanced option, after initialization:

1
2
3
4
5
 
// getter
var enhanced = $( ".selector" ).button( "option", "enhanced" );
 
// setter
$( ".selector" ).button( "option", "enhanced", true );

iconType: String

Default: null
Applies an icon from the icon set.

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".

Code examples:

Initialize the button with the icon option specified:

1
 
$( ".selector" ).button({ icon: "star" });

Get or set the icon option, after initialization:

1
2
3
4
5
 
// getter
var icon = $( ".selector" ).button( "option", "icon" );
 
// setter
$( ".selector" ).button( "option", "icon", "star" );

iconposType: String

Default: "left"
Positions the icon in the button. Possible values: left, right, top, bottom, none, notext. The notext value will display an icon-only button with no text feedback.

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

iconshadowType: Boolean

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

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".

(version deprecated: 1.4.0)

initSelectorType: Selector

Default: See below

The default initSelector for the button widget is:

1
 
"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:

1
2
3
 
$( 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)

inlineType: Boolean

Default: null (false)
If set to 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".

miniType: Boolean

Default: null (false)
If set to 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".

shadowType: Boolean

Default: true
Applies the drop shadow style to the button if set to true.

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

themeType: String

Default: null, inherited from parent
Sets the color scheme (swatch) for the button widget. It accepts a single letter from a-z that maps to the swatches included in your theme.

Possible values: swatch letter (a-z).

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

Code examples:

Initialize the button with the theme option specified:

1
 
$( ".selector" ).button({ theme: "b" });

Get or set the theme option, after initialization:

1
2
3
4
5
 
// getter
var theme = $( ".selector" ).button( "option", "theme" );
 
// setter
$( ".selector" ).button( "option", "theme", "b" );

wrapperClassType: String

Default: null
Allows you to specify CSS classes to be set on the button's wrapper element.

This option is also exposed as a data attribute: data-wrapper-class="custom-class".

Methods

destroy()Returns: jQuery (plugin only)

Removes the button functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
 
$( ".selector" ).button( "destroy" );

disable()Returns: jQuery (plugin only)

Disables the button.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

1
 
$( ".selector" ).button( "disable" );

enable()Returns: jQuery (plugin only)

Enables the button.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

1
 
$( ".selector" ).button( "enable" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
 
var isDisabled = $( ".selector" ).button( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current button options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
var options = $( ".selector" ).button( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the button option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
 
$( ".selector" ).button( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the button.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

1
 
$( ".selector" ).button( "option", { disabled: true } );

refresh()Returns: jQuery (plugin only)

update the form button.

If you manipulate a form button via JavaScript, you must call the refresh method on it to update the visual styling.

1
 
$( "[type='submit']" ).button( "refresh" );
  • This method does not accept any arguments.
Code examples:

Invoke the refresh method:

1
 
$( ".selector" ).button( "refresh" );

Events

create( event, ui )Type: buttoncreate

Triggered when the button is created.

Note: The ui object is empty but included for consistency with other events.

Code examples:

Initialize the button with the create callback specified:

1
2
3
 
$( ".selector" ).button({
  create: function( event, ui ) {}
});

Bind an event listener to the buttoncreate event:

1
 
$( ".selector" ).on( "buttoncreate", function( event, ui ) {} );

Example:

A basic example of a button

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
<!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="http://code.jquery.com/mobile/1.4.4/jquery.mobile-1.4.4.min.css">
  <script src="http://code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="http://code.jquery.com/mobile/1.4.4/jquery.mobile-1.4.4.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>

Demo: