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, displaying 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 displays "Unfollow" when you mouse over it or when it receives focus.

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

lightning-button-stateful implements the stateful buttons blueprint in the Salesforce Lightning Design System (SLDS).

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.

Visit utility icons to view the utility icons.

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.

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available.

See Buttons: Styling Hooks Overview for documentation on component-specific hooks for this component. lightning-button-stateful contains the same customizable elements as lightning-button, which supports --slds-c-button-* custom properties. 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.