jQuery UI API - Button Widget
Category
Usage
Description: Themable buttons and button sets.
Version Added: 1.8
The Button Widget enhances the functionality of standard form elements like buttons, inputs, and anchors by adding appropriate hover and active styles, and theming the buttons.
In addition to basic buttons, radio buttons and checkboxes (input types radio and checkbox) can also be converted into buttons. The associated labels are styled to look like buttons, and clicking on them updates the underlying input. To work correctly, the input needs to have an id attribute, and the label needs to have a for attribute pointing to the input's id. Do not place the input inside the label, as this can cause accessibility issues.
For grouping radio buttons, Button also provides an additional widget called Buttonset. Buttonset is used by selecting a container element (containing the radio buttons) and calling .buttonset(). Buttonset also provides visual grouping, so it can be considered for use when there is a set of buttons. It selects all descendants and applies .button() to them. You can enable and disable a button set, which will enable and disable all contained buttons. Destroying a button set will call the destroy method on each button. For grouped radio buttons and checkbox buttons, it is recommended to use a fieldset with a legend to provide an accessible grouping label.
When using an input of type button, submit, or reset, it is limited to supporting plain text labels without icons.
Theming
The Button Widget uses the jQuery UI CSS Framework to define its appearance and style. To use the styles specific to buttons, you can use the following CSS class names:
ui-button: Represents the DOM element of the button. This element will add one of the following classes based on thetextandiconsoptions:ui-button-text-only,ui-button-icon-only,ui-button-icons-only,ui-button-text-icons.ui-button-icon-primary: The element used to display the primary icon of the button. This is rendered only if the primary icon is provided in theiconsoption.ui-button-text: The container around the button's text content.ui-button-icon-secondary: The element used to display the secondary icon of the button. This is rendered only if the secondary icon is provided in theiconsoption.ui-buttonset: The outer container of the Buttonset.
Dependencies
Additional Notes
- This widget requires some functional CSS, otherwise it will not work. If you are creating a custom theme, use the widget-specific CSS file as a starting point.
Quick Navigation
| Options | Methods | Events |
|---|---|---|
| disabled icons label text | destroy disable enable option refresh widget | create |
| Options | Type | Description | Default Value |
|---|---|---|---|
| disabled | Boolean | If set to true, the button will be disabled. <br> Code example: Initialize a button with the specified disabled option: $( ".selector" ).button({ disabled: true }); After initialization, get or set the disabled option: // getter<br>var disabled = $( ".selector" ).button( "option", "disabled" );<br> <br>// setter<br>$( ".selector" ).button( "option", "disabled", true ); | false |
| icons | Object | Icons to display, including icons with text and icons without text (see text <br> The primary and secondary property values must be icon class names, such as "ui-icon-gear". If only one icon is used, icons: { primary: "ui-icon-locked" }. If two icons are used, icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" }. Code example: Initialize a button with the specified icons option: $( ".selector" ).button({ icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } }); After initialization, get or set the disabled option: // getter<br>var icons = $( ".selector" ).button( "option", "icons" );<br> <br>// setter<br>$( ".selector" ).button( "option", "icons", { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } ); | { primary: null, secondary: null } |
| label | String | The text to display on the button. When unspecified (null), the HTML content of the element is used, or if the element is a submit or reset type input element, its value attribute is used, or if the element is a radio or checkbox type input element, the HTML content of the associated label element is used. <br> Code example: Initialize a button with the specified label option: $( ".selector" ).button({ label: "custom label" }); After initialization, get or set the label option: // getter<br>var label = $( ".selector" ).button( "option", "label" );<br> <br>// setter<br>$( ".selector" ).button( "option", "label", "custom label" ); | null |
| text | Boolean | Whether to display the label. When set to false, the text is not displayed, but at this time, the icons option must be enabled. The text option will be ignored. <br> Code example: Initialize a button with the specified text option: $( ".selector" ).button({ text: false }); After initialization, get or set the text option: // getter<br>var text = $( ".selector" ).button( "option", "text" );<br> <br>// setter<br>$( ".selector" ).button( "option", "text", false ); | true |
| Method | Return | Description |
|---|---|---|
| destroy() | jQuery (plugin only) | Completely removes the button functionality. This returns the element to its pre-initialization state. <br> This method does not accept any parameters. Code example: Call the destroy method: $( ".selector" ).button( "destroy" ); |
| disable() | jQuery (plugin only) | Disable the button. <br> This method does not accept any parameters. Code example: Invoke the disable method: $( ".selector" ).button( "disable" ); |
| enable() | jQuery (plugin only) | Enable the button. <br> This method does not accept any parameters. Code example: Invoke the enable method: $( ".selector" ).button( "enable" ); |
| option( optionName ) | Object | Retrieve the value currently associated with the specified optionName. <br> optionName<br> Type: String<br> Description: The name of the option to get. Code example: Invoke the method: var isDisabled = $( ".selector" ).button( "option", "disabled" ); |
| option() | PlainObject | Retrieve an object containing key/value pairs representing the current button options hash. <br> This method does not accept any parameters. Code example: Invoke the method: var options = $( ".selector" ).button( "option" ); |
| option( optionName, value ) | jQuery (plugin only) | Set the value of the button option associated with the specified optionName. <br> optionName<br> Type: String<br> Description: The name of the option to set.<br> value<br> Type: Object<br> Description: A value to set for the option. Code example: Invoke the method: $( ".selector" ).button( "option", "disabled", true ); |
| option( options ) | jQuery (plugin only) | Set one or more options for the button. <br> options<br> Type: Object<br> Description: A map of option-value pairs to set. Code example: Invoke the method: $( ".selector" ).button( "option", { disabled: true } ); |
| refresh() | jQuery (plugin only) | Refresh the visual state of the button. Useful for updating the button state after the native element's checked or disabled state is changed programmatically. <br> This method does not accept any parameters. Code example: Invoke the refresh method: $( ".selector" ).button( "refresh" ); |
| widget() | jQuery | Return a jQuery object containing the button. <br> This method does not accept any parameters. Code example: Invoke the widget method: var widget = $( ".selector" ).button( "widget" ); |
| Event | Type | Description |
|---|---|---|
| create( event, ui ) | buttoncreate | Triggered when the button is created. <br> event<br> Type: Event<br> ui<br> Type: Object Note: The ui object is empty but included for consistency with other events. Code example: Initialize the button with the specified create callback: $( ".selector" ).button({<br> create: function( event, ui ) {}<br>}); Bind an event listener to the buttoncreate event: $( ".selector" ).on( "buttoncreate", function( event, ui ) {} ); |
Example
A simple jQuery UI Button.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Button Widget Demo</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<script>
$(function() {
$( "#button" ).button();
});
</script>
</head>
<body>
<button id="button">A Button</button>
</body>
</html>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<button>Button Tag</button>
<script>
$( "button" ).button();
</script>
</body>
</html>
A simple jQuery UI Buttonset.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Button Widget Demo</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<form>
<fieldset>
<legend>Favorite jQuery Projects</legend>
<div id="radio">
<input type="radio" id="sizzle" name="project">
<label for="sizzle">Sizzle</label>
<input type="radio" id="qunit" name="project" checked="checked">
<label for="qunit">QUnit</label>
<input type="radio" id="color" name="project">
<label for="color">Color</label>
</div>
</fieldset>
</form>
<script>
$( "#radio" ).buttonset();
</script>
</body>
</html>