jQuery UI API - Button Widget

Category

Widgets

Usage

Description:Themeable buttons and button sets.

Version added:1.8

The Button Widget enhances the functionality of standard form elements, such as buttons, inputs, and anchors, to theme them with appropriate hover and active styles.

In addition to basic buttons, radio buttons and checkboxes (input types radio and checkbox) can also be converted into buttons. The associated label is styled as a button, and clicking it updates the underlying input. For this to work properly, the input needs anidattribute, and it must point to the label'sforattribute. Do not place the input inside the label, otherwise it willcause accessibility issues。

To group radio buttons, Button also provides an additional widget named 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 whenever there is a group of buttons. It selects all descendants and applies.button(). You can enable and disable a buttonset, which will enable and disable all contained buttons. Destroying a buttonset invokes each button'sdestroymethod. For grouped radio buttons and checkbox buttons, it is recommended to use alegendoffieldsetto provide an accessible group label.

When using an input of type button, submit, or reset, only plain text labels without icons are supported.

Theming

The Button Widget uses thejQuery UI CSS Frameworkto define the styling of its look and feel. If you need to use button-specific styles, you can use the following CSS class names:

  • ui-button: Represents the DOM element of the button. This element will be given one of the following classes based on thetextandiconsoption: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 button's primary icon. It is rendered only when the primary icon is provided in theiconsoption.
    • ui-button-text: The container surrounding the button's text content.
    • ui-button-icon-secondary: Used to display the button's secondary icon. It is rendered only when 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 create a custom theme, use the widget-specific CSS file as a starting point.

Quick Navigation

Options Methods Events

Options Type Description Default
disabled Boolean If set totrue, the button is disabled.

Code examples:

Initialize the button with the specifieddisabledoption:

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

After initialization, get or set thedisabledoption:

// getter
var disabled = $( ".selector" ).button( "option", "disabled" );
 
// setter
$( ".selector" ).button( "option", "disabled", true );
    
 false
icons Object Icons to display, including icons with text and icons without text (see thetextoption). By default, the primary icon is displayed to the left of the label text, and the secondary icon is displayed to the right. The display position can be controlled via CSS.

primaryandsecondaryThe attribute value must be anicon class name, for example,"ui-icon-gear". If only one icon is used, thenicons: { primary: "ui-icon-locked" }. If two icons are used, thenicons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" }。

Code examples:

Initialize the button with the specifiediconsoption:

$( ".selector" ).button({ icons: { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } });
    

After initialization, get or set thedisabledoption:

// getter
var icons = $( ".selector" ).button( "option", "icons" );
 
// setter
$( ".selector" ).button( "option", "icons", { primary: "ui-icon-gear", secondary: "ui-icon-triangle-1-s" } );
    
 { primary: null, secondary: null }
label String The text to display in the button. When not specified (null), the HTML content of the element is used, or if the element is an input element of type submit or reset, itsvalueattribute is used, or if the element is an input element of type radio or checkbox, the HTML content of the associated label element is used.

Code examples:

Initialize the button with the specifiedlabeloption:

$( ".selector" ).button({ label: "custom label" });
    

After initialization, get or set thelabeloption:

// getter
var label = $( ".selector" ).button( "option", "label" );
 
// setter
$( ".selector" ).button( "option", "label", "custom label" );
    
 null
text Boolean Whether to display the label. When set tofalse, the text is not displayed, but theiconsoption must be enabled, otherwise thetextoption will be ignored.

Code examples:

Initialize the button with the specifiedtextoption:

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

After initialization, get or set thetextoption:

// getter
var text = $( ".selector" ).button( "option", "text" );
 
// setter
$( ".selector" ).button( "option", "text", false );
    
 true

Methods Returns Description
destroy() jQuery (plugin only) Completely removes the button functionality. This returns the element to its pre-initialization state.
  • This method does not accept any arguments.

Code examples:

Invoke the destroy method:

$( ".selector" ).button( "destroy" );
    
disable() jQuery (plugin only) Disables the button.
  • This method does not accept any arguments.

Code examples:

Invoke the disable method:

$( ".selector" ).button( "disable" );
    
enable() jQuery (plugin only) Enables the button.
  • This method does not accept any arguments.

Code examples:

Invoke the enable method:

$( ".selector" ).button( "enable" );
    
option( optionName ) Object Gets the value currently associated with the specifiedoptionNameoption.
  • optionName
    Type: String
    Description: The name of the option to get.

Code examples:

Invoke the method:

var isDisabled = $( ".selector" ).button( "option", "disabled" );
    
option() PlainObject Gets an object containing key/value pairs that represent the current button options hash.
  • This method does not accept any arguments.

Code examples:

Invoke the method:

var options = $( ".selector" ).button( "option" );
    
option( optionName, value ) jQuery (plugin only) Sets the value of the button option associated with the specifiedoptionNameoption.
  • optionName
    Type: String
    Description: The name of the option to set.
  • value
    Type: Object
    Description: The value to set for the option.

Code examples:

Invoke the method:

$( ".selector" ).button( "option", "disabled", true );
    
option( options ) jQuery (plugin only) Sets one or more options for the button.
  • options
    Type: Object
    Description: The option-value pairs to set.

Code examples:

Invoke the method:

$( ".selector" ).button( "option", { disabled: true } );
    
refresh() jQuery (plugin only) Refreshes the visual state of the button. Used to update the button state after programmatically changing the selection state or disabled state of the native element.
  • This method does not accept any arguments.

Code examples:

Invoke the refresh method:

$( ".selector" ).button( "refresh" );
    
widget() jQuery Returns a jQuery object containing thejQuerybutton.
  • This method does not accept any arguments.

Code examples:

Invoke the widget method:

var widget = $( ".selector" ).button( "widget" );
    

Events Type Description
create( event, ui ) buttoncreate Triggered when a button is created.
  • event
    Type: Event
  • ui
    Type: Object

Note:uiThe object is empty, and it is included here for consistency with other events.

Code examples:

Initialize the button with the specified create callback:

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

Bind an event listener to the buttoncreate event:

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

Examples

Example 1:

A simple jQuery UI Button.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>按钮部件（Button Widget）演示</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>
 
<button>按钮标签</button>
 
<script>
$( "button" ).button();
</script>
 
</body>
</html>

Example 2:

A simple jQuery UI Buttonset.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>按钮部件（Button Widget）演示</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>最喜欢的 jQuery 项目</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>

Other extensions