--- schema_version: "1" id: 9ae56b9dadde860ec64284b2093947bf117c07a390c72ddbeaadd8bd4c91692d title: Button Stateful collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/buttonStateful/lightning-button-stateful.md canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-stateful.html source_site: developer.salesforce.com content_type: documentation content_hash: 6c687de2a6592d70a817f7ce1999a495dc7aba5742bb177c1bf8522d5bafd6e0 products: - Lightning Component Reference --- # Button Stateful **`lightning-button-stateful`** A button that toggles between states. **For Use In** Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline ::::::tabset{tabs='["Example", "Develop", "Specifications"]'} :::::tab ::component-playground{component="buttonStateful" model="lwc" namespace="lightning"} ::::: :::::tab 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. ```html ``` The `handleClick()` function toggles the state via the `isSelected` attribute. ```javascript import { LightningElement } from "lwc"; export default class MyComponentName extends LightningElement { isSelected = false; handleClick() { this.isSelected = !this.isSelected; } } ``` `lightning-button-stateful` doesn't retrieve the button label from `event.target.label`. To work with the button labels, use the `labelWhenOff`, `labelWhenOn`, and `labelWhenHover` attributes. ## Design `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. | | SLDS 1 | SLDS 2 | | :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- | | **Design** | [Buttons (Stateful)](https://v1.lightningdesignsystem.com/components/buttons/#flavor-stateful) | [Buttons (Stateful)](https://www.lightningdesignsystem.com/components/buttons/#flavor-stateful) | | **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) | ## Component Styling Use a combination of icon names, variants, and utility classes to style your stateful buttons. ### Icons Use the `icon-name` attribute to add a utility icon to the button. The [SLDS utility icon category](https://v1.lightningdesignsystem.com/icons/#utility) 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. ### Variants 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. ### Utility Classes To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute. This example adds padding on the button using an SLDS class. ```html ``` ### Styling Hooks 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](https://v1.lightningdesignsystem.com/components/overview/) for available component styling hooks. For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) 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. | CSS Custom Property | `lightning-button-stateful` Variants | | ------------------------------- | ------------------------------------ | | `--slds-c-button-*` | all | | `--slds-c-button-color-*` | `base` | | `--slds-c-button-text-color-*` | `neutral` (default) and `text` | | `--slds-c-button-neutral-*` | `neutral` (default) | | `--slds-c-button-brand-*` | `brand` | | `--slds-c-button-destructive-*` | `destructive` | | `--slds-c-button-inverse-*` | `inverse` | | `--slds-c-button-success-*` | `success` | For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide. ## Usage Considerations This component has usage differences from its Aura counterpart. See [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/platform/lwc/guide/migrate-map-aura-lwc-components) in the Lightning Web Components Developer Guide. ## Accessibility 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. ::::: :::::tab ::component-specification{component="buttonStateful" model="lwc" namespace="lightning"} ::::: ::::::