<div class='intro'>

<p>{{description}}</p>

</div>

{{>getting-started}}

<h2>Using Button</h2>

<h3>Quick Start</h3>

```

// Create some button widgets

YUI().use('button', function(Y){

// Create a push button widget

var button = new Y.Button({

srcNode: '#myButton'

});

// Create a toggle button widget

var toggleButton = new Y.ToggleButton({

srcNode: '#myToggleButton'

});

// Change the push button's label

button.set('label', "I'm a YUI Button!");

// Activate the toggle button's 'pressed' state

toggleButton.set('pressed', true);

});

// Create some lighter-weight buttons by plugging nodes

YUI().use('button-plugin', function(Y){

// Plug an existing node

var button = new Y.Plugin.Button.nodeCreate("#testButton", {

label: "I'm a disabled button",

disabled: true

});

button.set('disabled', false);

button.set('label', 'Not anymore!');

button.on('click', function(){

Y.log('I was clicked!');

});

});

// Create a button group widget

YUI().use('button-group', function(Y){

// Use an existing node to create a toggle button widget

var buttonGroup = new Y.ButtonGroup({

srcNode: '#container' // Should contain <button> children

});

// Get an array of buttons that have a selected (pressed/checked) state

var buttons = ButtonGroup.getSelectedButtons();

});

```

<h2>Anatomy</h2>

<p>YUI's Button component introduces 5 modules:</p>

<ul>

<li><a href="#cssbutton">`cssbutton`</a> - Includes various `yui3-button` styles to provide a normalized CSS base for buttons.</li>

<li><a href="#button">`button`</a> - Exports the `Y.Button` &amp; `Y.ToggleButton` widgets.</li>

<li><a href="#buttongroup">`button-group`</a> - Exports the `Y.ButtonGroup` widget.</li>

<li><a href="#buttonplugin">`button-plugin`</a> - Exports the `Y.Plugin.Button.createNode` factory.</li>

<li>`button-core` - Exports `Y.ButtonCore`, a base used by all other Button component modules.</li>

</ul>

<h3>Which one to use?</h3>

<ul>

<li>`use('cssbutton')` if you only want CSS-styled buttons</li>

<li>`use('button')` if you want a button widget</li>

<li>`use('button-group')` if you want to manage a group of buttons (widget)</li>

<li>`use('button-plugin')` if you only need a enhance a Y.Node instance with button functionality</li>

<li>`button-core` is not intended to be used stand-alone</li>

</ul>

<h2>Modules</h2>

<div id="cssbutton">

<h3>cssbutton</h3>

<p>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.</p>

```

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

```

<p>Loading this stylesheet will include the following classes:</p>

<ul>

<li>yui3-button</li>

<li>yui3-button-disabled</li>

<li>yui3-button-hover, yui3-button:hover</li>

<li>yui3-button-active, yui3-button:active</li>

<li>yui3-button-primary, yui3-button-selected</li>

</ul>

<p>These styles are designed to progressively enhance. In legacy browsers, you'll get styles that appear a bit nicer than native buttons, and in modern browsers you'll get buttons using modern CSS3 styles. These are intended to be base styles and all overridable.</p>

<h4>Background Color</h4>

<p>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 one style, `background-color` and apply it to your buttons.</p>

</div>

<div id="button">

<h3>button</h3>

<h4>Y.Button</h4>

<h5>Benefits of Y.Button</h5>

<p>So what do you get from Y.Button over just creating your own button node, via something like `new Y.Node.create('<button></button>')`</p>

<ul>

<li><strong>State management</strong> - 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' (depending on `type`) event only when the button state changes from selected to unselected, or vice-versa, eliminating the typical case of listening for 'click' and then checking to see if a state changed.</li>

<li><strong>Accessibility</strong> - Your buttons automatically create and manage their own ARIA <a href='http://www.w3.org/TR/wai-aria/states_and_properties'>states</a> &amp; <a href='http://www.w3.org/TR/wai-aria/roles'>roles</a>. This includes states like `aria-pressed` &amp; `aria-checked`, also appropriate roles like `button`, `checked`, `radio`, etc...</li>

<li><strong>Groups</strong> - `Y.ButtonGroup` allows you to group buttons together to create checkbox &amp; radio groups, giving your users a nicer experience when compared to the standard `<input type='radio'>` or `<input type='checkbox'>` controls.</li>

</ul>

<h5>Events</h5>

<p>Most commonly with button elements, you want to listen for any clicks, or other <a href='/yui/docs/api/files/node_js_node-event.js.html#l8'>DOM events</a> that occur.</p>

```

var button = new Y.Button({

srcNode: '#myButton'

});

var node = button.getNode();

node.on('click', function(){

alert('Hello!');

});

```

<p>If you are more interested in listening to a `button`'s attribute change events, that can be done at creation.</p>

```

var button = new Y.ToggleButton({

srcNode: '#myButton',

on: {

labelChange: function(){

Y.log('This will fire when the toggled state changes')

}

}

})

```

<p>Any event handlers can also be assigned by using the `on` property in the configuration object. Valid events include any , as well as Y.Button attribute change events (e.g. 'selectedChange').</p>

<h4>Y.ToggleButton</h4>

<p>`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 button.</p>

</div>

<div id="buttonplugin">

<h3>button-plugin</h3>

<p>This module exports the Y.Plugin.Node.createNode factory, which simplifies the process of plugging nodes.</p>

</div>

<div id="buttongroup">

<h3>button-group</h3>

<h4>Y.ButtonGroup</h4>

<p>`Y.ButtonGroup` is a constructor that is used to generate widgets containing a group of buttons. To avoid widgets inside of widgets, this class is built on top of `Y.ButtonCore`</p>

</div>

<h2>Reference</h2>

<h3>Attributes</h3>

<h4>Y.ButtonCore</h4>

<table>

<thead>

<tr>

<th>Attribute</th>

<th>Data type</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>label</td>

<td>string</td>

<td>

Sets the button's `innerHTML` or `value` attribute depending on node type

</td>

</tr>

<tr>

<td>disabled</td>

<td>boolean</td>

<td>

Sets the button's disabled state to true/false

</td>

</tr>

</tbody>

</table>

<h4>Node Plugin</h4>

<p>Inherited from `Y.ButtonCore`</p>

<h4>Y.Button</h4>

<p>Identical to `Y.ButtonCore`</p>

<h4>Y.ToggleButton</h4>

<p>In addition to the inherited `Y.Button` attributes...</p>

<table>

<thead>

<tr>

<th>Attribute</th>

<th>Data type</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>type</td>

<td>string</td>

<td>

'toggle' (default),

<br>'checkbox' (multi-select)

</td>

</tr>

</tbody>

</table>

<h4>Y.ButtonGroup</h4>

<p>In addition to the inherited `Y.ButtonCore` attributes...</p>

<table>

<thead>

<tr>

<th>Attribute</th>

<th>Data type</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>type</td>

<td>string</td>

<td>

'push' (default),

<br>'radio' (single-select),

<br>'checkbox' (multi-select)

</td>

</tr>

</tbody>

</table>

<h3>Events</h3>

<p>

Note:

<br>`.on('eventName', fn)` will fire <strong>before</strong> the attribute &amp; UI are updated.

<br>`.after('eventName', fn)` will fire <strong>after</strong> the attribute &amp; UI are updated.

</p>

<h4>Y.ButtonCore</h4>

<table>

<thead>

<tr>

<th>Event</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>labelChange</td>

<td>

Fires to inform the subscriber that the button's label is about to be, or has been updated.

</td>

</tr>

<tr>

<td>disabledChange</td>

<td>

Fires to notify the subscriber the disabled state is about to be, or has been updated.

</td>

</tr>

</tbody>

</table>

<h4>Node Plugin</h4>

<p>Inherited from `Y.ButtonCore`</p>

<h4>Y.Button</h4>

<p>Identical to `Y.ButtonCore`</p>

<h4>Y.ToggleButton</h4>

<p>In addition to the inherited `Y.Button` events...</p>

<table>

<thead>

<tr>

<th>Event</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>pressedChange</td>

<td>

Fires for toggle buttons to notify the subscriber the selected state is about to be, or has been updated.

</td>

</tr>

<tr>

<td>checkedChange</td>

<td>

Identical to `"pressedChange"`, but only applicable for buttons with a configuration attribute `"type: 'checkbox'"`.

</td>

</tr>

</tbody>

</table>

<h4>Y.ButtonGroup</h4>

<p>In addition to the inherited `Y.ButtonCore` events...</p>

<table>

<thead>

<tr>

<th>Event</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>selectionChange</td>

<td>

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.

</td>

</tr>

</tbody>

</table>