Button Stateful

A lightning-button-stateful 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 selected states.

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, showing the “Follow” label by default, and replacing it with “Following” when the button is selected. Selecting the button toggles the selected state to true, and deselecting it toggles selected state to false. When the selected state is true, the button shows “Unfollow” when you mouse over it or when it receives focus.

1<template>
2    <lightning-button-stateful
3        label-when-off="Follow"
4        label-when-on="Following"
5        label-when-hover="Unfollow"
6        icon-name-when-off="utility:add"
7        icon-name-when-on="utility:check"
8        icon-name-when-hover="utility:close"
9        selected={isSelected}
10        onclick={handleClick}
11    >
12    </lightning-button-stateful>
13</template>

The handleClick() function toggles the state via the isSelected attribute.

1import { LightningElement } from "lwc";
2
3export default class MyComponentName extends LightningElement {
4  isSelected = false;
5
6  handleClick() {
7    this.isSelected = !this.isSelected;
8  }
9}

lightning-button-stateful implements the buttons blueprint in the Salesforce Lightning Design System (SLDS). The buttons adapt to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

Use a combination of icon names, variants, and utility classes to style your stateful buttons.

Use the icon-name attribute to add a utility icon to the button.

The SLDS utility icon category provides nearly 200 utility icons that can be used in lightning-button-stateful along with a text label. Although SLDS provides several categories of icons, only the utility category can be used with this component.

When applying SLDS classes or icons, check that they are available in the SLDS release tied to your org. The latest SLDS resources become available only when the new release is available in your org.

Use the variant attribute with one of these values to apply styling.

• neutral is the default variant, a plain uncolored button.
• brand is a blue button, used to draw attention to the primary action on a page.
• destructive is a red button used to warn users that its action has a negative effect.
• inverse uses the background color and light text, useful for dark backgrounds.
• success is a green button used to indicate a successful action.
• text is a button without a border, which gives it the look of a plain text link.

To apply additional styling, use the SLDS utility classes with the class attribute.

This example adds padding on the button using an SLDS class.

1<lightning-button-stateful
2    label-when-off="Follow"
3    label-when-on="Following"
4    label-when-hover="Unfollow"
5    icon-name-when-off="utility:add"
6    icon-name-when-on="utility:check"
7    icon-name-when-hover="utility:close"
8    selected={isSelected}
9    onclick={handleClick}
10    class="slds-p-around_medium"
11>
12</lightning-button-stateful>

Component styling hooks provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

lightning-button-stateful contains the same customizable elements as lightning-button, which supports --slds-c-button-* custom properties. CSS custom properties for stateful buttons work only with particular lightning-button-stateful variants.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

This component has usage differences from its Aura counterpart. See Base Components: Aura Vs Lightning Web Components in the Lightning Web Components Developer Guide.

This component uses aria-live="polite", which means the button label is read after the current user task or content.

To inform screen readers that a button is disabled, set the disabled attribute to true.