Button Widget
Button Widgetversion added: 1.8
Description: Themeable buttons and button sets.
QuickNavExamples
Events
Button enhances standard form elements like buttons, inputs and anchors to themeable buttons with appropriate hover and active styles.
In addition to basic push buttons, radio buttons and checkboxes (inputs of type radio and checkbox) can be converted to buttons. Their associated label is styled to appear as the button, while the underlying input is updated on click. For the association to work properly, give the input an id
attribute, and refer to that in the label's for
attribute. Don't nest the input inside the label, as that causes accessibility problems.
In order to group radio buttons, Button also provides an additional widget, called Buttonset. Buttonset is used by selecting a container element (which contains the radio buttons) and calling .buttonset()
. Buttonset will also provide visual grouping, and therefore should be used whenever you have a group of buttons. It works by selecting all descendants and applying .button()
to them. You can enable and disable a button set, which will enable and disable all contained buttons. Destroying a button set also calls each button's destroy
method.
When using an input of type button, submit or reset, support is limited to plain text labels with no icons.
Dependencies
Additional Notes:
- This widget requires some functional CSS, otherwise it won't work. If you build a custom theme, use the widget's specific CSS file as a starting point.
Options
disabledType: Boolean
false
true
.
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 );
|
iconsType: Object
{ primary: null, secondary: null }
text
option). By default, the primary icon is displayed on the left of the label text and the secondary is displayed on the right. The positioning can be controlled via CSS. The value for the
primary
and
secondary
properties must be a class name, e.g.,
"ui-icon-gear"
. For using only one icon:
icons: { primary: "ui-icon-locked" }
. For using two icons:
icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" }
.
Initialize the button with the icons option specified:
1
|
$( ".selector" ).button({ icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } });
|
Get or set the icons option, after initialization:
1
2
3
4
5
|
// getter
var icons = $( ".selector" ).button( "option", "icons" );
// setter
$( ".selector" ).button( "option", "icons", { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } );
|
labelType: String
null
null
), the element's HTML content is used, or its
value
attribute if the element is an input element of type submit or reset, or the HTML content of the associated label element if the element is an input of type radio or checkbox.
Initialize the button with the label option specified:
1
|
$( ".selector" ).button({ label: "custom label" });
|
Get or set the label option, after initialization:
1
2
3
4
5
|
// getter
var label = $( ".selector" ).button( "option", "label" );
// setter
$( ".selector" ).button( "option", "label", "custom label" );
|
textType: Boolean
true
false
no text will be displayed, but the
icons
option must be enabled, otherwise the
text
option will be ignored.
Initialize the button with the text option specified:
1
|
$( ".selector" ).button({ text: false });
|
Get or set the text option, after initialization:
1
2
3
4
5
|
// getter
var text = $( ".selector" ).button( "option", "text" );
// setter
$( ".selector" ).button( "option", "text", false );
|
Methods
destroy()
-
This method does not accept any arguments.
Invoke the destroy method:
1
|
$( ".selector" ).button( "destroy" );
|
disable()
-
This method does not accept any arguments.
Invoke the disable method:
1
|
$( ".selector" ).button( "disable" );
|
enable()
-
This method does not accept any arguments.
Invoke the enable method:
1
|
$( ".selector" ).button( "enable" );
|
option( optionName )Returns: Object
optionName
.
-
optionNameType: StringThe name of the option to get.
Invoke the method:
1
|
var isDisabled = $( ".selector" ).button( "option", "disabled" );
|
option()Returns: PlainObject
-
This method does not accept any arguments.
Invoke the method:
1
|
var options = $( ".selector" ).button( "option" );
|
option( optionName, value )
optionName
.
-
optionNameType: StringThe name of the option to set.
-
valueType: ObjectA value to set for the option.
Invoke the method:
1
|
$( ".selector" ).button( "option", "disabled", true );
|
option( options )
-
optionsType: ObjectA map of option-value pairs to set.
Invoke the method:
1
|
$( ".selector" ).button( "option", { disabled: true } );
|
refresh()
-
This method does not accept any arguments.
Invoke the refresh method:
1
|
$( ".selector" ).button( "refresh" );
|
widget()Returns: jQuery
jQuery
object containing the element visually representing the button.
-
This method does not accept any arguments.
Invoke the widget method:
1
|
var widget = $( ".selector" ).button( "widget" );
|
Events
create( event, ui )Type: buttoncreate
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 ) {} );
|
Examples:
Example: A simple jQuery UI Button
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>button demo</title>
<link rel="stylesheet" href="http://code.jquery.com/ui/1.10.2/themes/smoothness/jquery-ui.css">
<script src="http://code.jquery.com/jquery-1.9.1.js"></script>
<script src="http://code.jquery.com/ui/1.10.2/jquery-ui.js"></script>
</head>
<body>
<button>Button label</button>
<script>
$( "button" ).button();
</script>
</body>
</html>
|
Demo:
Example: A simple jQuery UI Buttonset
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>button demo</title>
<link rel="stylesheet" href="http://code.jquery.com/ui/1.10.2/themes/smoothness/jquery-ui.css">
<script src="http://code.jquery.com/jquery-1.9.1.js"></script>
<script src="http://code.jquery.com/ui/1.10.2/jquery-ui.js"></script>
</head>
<body>
<div id="radio">
<input type="radio" id="radio1" name="radio"><label for="radio1">Choice 1</label>
<input type="radio" id="radio2" name="radio" checked="checked"><label for="radio2">Choice 2</label>
<input type="radio" id="radio3" name="radio"><label for="radio3">Choice 3</label>
</div>
<script>
$( "#radio" ).buttonset();
</script>
</body>
</html>
|