A lightning:buttonStateful component represents a button that toggles between states, similar to a like button on social media. Stateful buttons can show a different label and icon based on their states.
Use the variant and class attributes to apply additional styling.
The Lightning Design System utility icon category provides nearly 200 utility icons that can be used in lightning:button along with a text label. Although the Lightning Design System provides several categories of icons, only the utility category can be used with this component.
Visit https://lightningdesignsystem.com/icons/#utility to view the utility icons.
This component inherits styling from stateful buttons in the Lightning Design System.
To handle the state change when the button is clicked, use the onclick event handler. This example enables you to toggle the button between states, displaying the "Follow" label by default, and replacing it with "Following" when the button is selected. Selecting the button toggles the state to true, and deselecting it toggles the state to false. When the state is true, the button displays "Unfollow" when you mouse over it or when it receives focus.
<aura:component> <aura:attribute name="buttonstate" type="Boolean" default="false"/> <lightning:buttonStateful labelWhenOff="Follow" labelWhenOn="Following" labelWhenHover="Unfollow" iconNameWhenOff="utility:add" iconNameWhenOn="utility:check" iconNameWhenHover="utility:close" state="{! v.buttonstate }" onclick="{! c.handleClick }" /> </aura:component>
The client-side controller toggles the state via the buttonstate attribute.
({ handleClick : function (cmp, event, helper) { var buttonstate = cmp.get('v.buttonstate'); cmp.set('v.buttonstate', !buttonstate); } })
For accessibility, include the attribute aria-live="assertive" on the button. The aria-live="assertive" attribute means the value of the <span> inside the button will be spoken whenever it changes.
To inform screen readers that a button is disabled, set the disabled attribute to true.
MethodsThis component supports the following method.
focus(): Sets the focus on the element.
Attribute Name | Attribute Type | Description | Required? |
---|---|---|---|
accesskey | String | Specifies a shortcut key to activate or focus an element. | |
body | Component[] | The body of the component. In markup, this is everything in the body of the tag. | |
class | String | A CSS class for the outer element, in addition to the component's base classes. | |
iconNameWhenHover | String | The name of the icon to be used in the format \'utility:close\' when the state is true and the button receives focus. | |
iconNameWhenOff | String | The name of the icon to be used in the format \'utility:add\' when the state is false. | |
iconNameWhenOn | String | The name of the icon to be used in the format \'utility:check\' when the state is true. | |
labelWhenHover | String | The text to be displayed inside the button when state is true and the button receives focus. | |
labelWhenOff | String | The text to be displayed inside the button when state is false. | Yes |
labelWhenOn | String | The text to be displayed inside the button when state is true. | Yes |
onblur | Action | The action triggered when the element releases focus. | |
onclick | Action | The action triggered when the button is clicked. | |
onfocus | Action | The action triggered when the element receives focus. | |
state | Boolean | The state of the button, which shows whether the button has been selected or not. The default state is false. | |
tabindex | Integer | Specifies the tab order of an element (when the tab button is used for navigating). | |
title | String | Displays tooltip text when the mouse moves over the element. | |
variant | String | The variant changes the appearance of the button. Accepted variants include brand, inverse, neutral and text. This value defaults to neutral. |