Version 3.18.1

Button

Jump to Table of Contents

YUI's Button component is a mixed-module approach to providing a simple-to-use button that normalizes and enhances the Web browser's default button component.

Getting Started

To include the source files for Button and its dependencies, first load the YUI seed file if you haven't already loaded it. 

<script src="http://yui.yahooapis.com/3.18.1/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify. 

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('button', function (Y) {
    // Button is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Using Button - Quick Start

Button Widgets

HTML

Note: be sure to add the yui3-skin-sam classname to the page's <body> element or to a parent element of the widget in order to apply the default CSS skin. See Understanding Skinning. 

<body class="yui3-skin-sam"> <!-- You need this skin class -->

    <button id="myButton">One</button>

JavaScript

// Create some button widgets
YUI().use('button', function(Y){

    // A push button widget
    var button = new Y.Button({
        srcNode: '#myButton'
    });

    // A toggle button widget
    var toggleButton = new Y.ToggleButton({
        srcNode: '#myToggleButton'
    });

});

Node Plugin

// If you want something a little more light-weight than a widget...
YUI().use('button-plugin', function(Y){

    var button = new Y.Plugin.Button.createNode("#testButton", {
        label: "I'm a disabled button",
        disabled: true
    });

});

Button Groups

HTML

Note: be sure to add the yui3-skin-sam classname to the page's <body> element or to a parent element of the widget in order to apply the default CSS skin. See Understanding Skinning. 

<body class="yui3-skin-sam"> <!-- You need this skin class -->

    <div id="container">
        <button class='yui3-button'>One</button>
        <button class='yui3-button'>Two</button>
        <button class='yui3-button'>Three</button>

JavaScript

// And if you want to manage a group of buttons
YUI().use('button-group', function(Y){

    var buttonGroup = new Y.ButtonGroup({
        srcNode: '#container' // Should contain <button> children
    });

});

Modules

YUI's Button component introduces 5 modules:

  • cssbutton - Includes various yui3-button styles to provide a normalized CSS base for buttons.
  • button - Exports the Y.Button & Y.ToggleButton widgets.
  • button-group - Exports the Y.ButtonGroup widget.
  • button-plugin - Exports the Y.Plugin.Button.createNode factory.
  • button-core - Exports Y.ButtonCore, a base used by all other Button component modules.

Which one to use?

  • use('cssbutton') if you only want a CSS stylesheet to enhance button(-like) nodes
  • use('button-plugin') if you only need to enhance a DOM node with button functionality
  • use('button') if you want a button widget
  • use('button-group') if you want a widget to manage a group of buttons
  • button-core is not intended to be used stand-alone

use('cssbutton')

YUI's Button component was designed with the idea in mind that sometimes you may only want button styles, without the need for any JavaScript functionality. Instead of use('button', ...), you can just include the cssbutton module. This can be done dynamically with use('cssbutton'), or statically with a link tag.

<link rel="stylesheet" href="http://yui.yahooapis.com/3.18.1/build/cssbutton/cssbutton.css">

Loading this stylesheet will include the following classes:

  • yui3-button
  • yui3-button-disabled
  • yui3-button-hover, yui3-button:hover
  • yui3-button-active, yui3-button:active
  • yui3-button-primary, yui3-button-selected

These styles are designed to progressively enhance. In legacy browsers, you'll get styles that appear as basic buttons, and in new browsers you'll get buttons using modern styles. cssbutton is intended to provide a base and be overridable with custom styles. Such as background-color.

Background Color

A feature of cssbutton is that it uses transparent gradients to create a colored effect. So if you would like a button that has a light to dark red gradient, you do not need to specify all the styles for proper cross-browser gradients, you only need to specify a single background-color style to your buttons.

use('button-core')

This module serves as the foundation for all Button component JavaScript modules and exports Y.ButtonCore. While you can use it stand-alone if you like, it is typically a foundational building block for all other Button classes.

use('button-plugin')

This module exports the Y.Plugin.Node.createNode factory, which simplifies the process of plugging nodes with Y.ButtonCore.

use('button')

Y.Button

Y.Button combines Y.ButtonCore with Y.Widget, to give you basic button functionality, but with the benefits of having a Widget instance. This can be used as a building block for different types of advanced buttons.

Y.ToggleButton

Y.ToggleButton does everything that Y.Button does (by extending it), and adds the concept of a selected state, which is referred to as either 'pressed' or 'checked', depending on the type attribute of the instance. This distinction is made for proper ARIA support.

Benefits

So what do you get from Y.Button/Y.ToggleButton over just creating or plugging a <button> node?

  • Accessibility - Your buttons automatically create and manage their own ARIA states & roles. This includes states like aria-pressed & aria-checked, also appropriate roles like button, checked, radio, etc...
  • State management - Instances automatically apply classes, such as yui3-button-selected and yui3-button-disabled which are useful for styling purposes. Also, Y.ToggleButton will fire a 'pressedChange' or 'checkedChange' event (depending on type) when the button's state changes from selected to unselected, or vice-versa. This event eliminates the typical case of listening for all 'click' events and then verifying a state changed actually did occur.

use('button-group')

Y.ButtonGroup is a constructor that is used to generate widgets containing a group of buttons.

Reference

Note: This is not an exhaustive list. See the API documentation for a complete listing.

Attributes

Y.ButtonCore

Attribute Data type Description
label string Sets the button's innerHTML or value attribute depending on node type
disabled boolean Sets the button's disabled state to true/false

Node Plugin

Inherited from Y.ButtonCore

Y.Button

Identical to Y.ButtonCore

Y.ToggleButton

In addition to the inherited Y.Button attributes...

Attribute Data type Description
type string

Sets the type of a toggleable button.

Possible values:

  • 'toggle' (default)
  • 'checkbox'

The difference is that a 'toggle' button will use aria-pressed, and a 'checkbox' button will use aria-checked.

Y.ButtonGroup

In addition to the inherited Y.Widget attributes...

Attribute Data type Description
type string

Sets the type of button group

Possible values:

  • 'push' (default) - No buttons have a selectable state
  • 'radio' - Only one button is selectable at a time
  • 'checkbox' - Multiple buttons can be selected at a time

Change Events

Y.ButtonCore

Event Description
labelChange Fires to inform the subscriber that the button's label is about to be, or has been updated.
disabledChange Fires to notify the subscriber the disabled state is about to be, or has been updated.

Node Plugin

Inherited from Y.ButtonCore

Y.Button

Identical to Y.ButtonCore

Y.ToggleButton

In addition to the inherited Y.Button events...

Event Description
pressedChange Fires for toggle buttons to notify the subscriber the selected state is about to be, or has been updated.
checkedChange Identical to "pressedChange", but only applicable for buttons with a configuration attribute "type: 'checkbox'".

Y.ButtonGroup

In addition to the inherited Y.Widget events...

Event Description
selectionChange Fires when a button within the group is either selected or unselected. The event payload contains a reference 'originEvent' to the original event, which can be used to obtain the target button.

Note:
.on('eventName', fn) will fire before the attribute & UI are updated.
.after('eventName', fn) will fire after the attribute & UI are updated.