Button Icon Stateful

A lightning-button-icon-stateful component represents an icon-only button element that toggles between two states. For example, you can use this component for capturing a customer’s feedback on a blog post (like or dislike). Clicking the button triggers the handler set for onclick. You can change the state of the icon by using the selected attribute.

This example creates a Like button that toggles between two states. The Like button is selected by default. The button’s state is stored in the selected attribute.

Selecting the Dislike button also toggles the state on the Like button and deselects it.

1<template>
2    <lightning-button-icon-stateful
3        icon-name="utility:like"
4        selected={liked}
5        alternative-text="Like"
6        onclick={handleToggle}
7    >
8    </lightning-button-icon-stateful>
9</template>

Handle the click event in your JavaScript code.

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

lightning-button-icon-stateful implements the button icons blueprint in the Salesforce Lightning Design System (SLDS). The button icons 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-name, variant, size, and class attributes to customize the button and icon styles.

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

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

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

• border is the default variant, an icon in a transparent container with a border
• border-filled shows an icon in a filled container with a border
• border-inverse shows an icon in a transparent container with a border, useful for dark backgrounds

Adjust the button and icon sizes by using the size attribute with one of these values.

• medium is the default size, which creates a 32px by 32px button enclosing a 14px by 14px icon.
• small creates a 24px by 24px button enclosing a 14px by 14px icon
• x-small creates a 20px by 20px button enclosing a 12px by 12px icon
• xx-small creates a 16px by 16px button enclosing a 8px by 8px icon

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

This example adds a margin to the left of the second button by using an SLDS class.

1<lightning-button-icon-stateful
2    icon-name="utility:like"
3    selected={likeState}
4    onclick={handleLikeButtonClick}
5    alternative-text="Like"
6></lightning-button-icon-stateful>
7<lightning-button-icon-stateful
8    icon-name="utility:answer"
9    selected={answerState}
10    onclick={handleAnswerButtonClick}
11    alternative-text="Answer"
12    class="slds-m-left_xx-small"
13></lightning-button-icon-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.

CSS custom properties for stateful button icons work only with specific lightning-button-icon-stateful variants.

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

Icons are not available in Lightning Out, but they are available in Lightning Components for Visualforce and other experiences.

lightning-button-icon-stateful contains an informational icon, which conveys information that surrounding text doesn’t. Each icon should be accompanied by either assistive text. When selected, the button renders with aria-pressed="true". When not selected, the button renders with aria-pressed="false". The aria-pressed attribute enables screen readers to announce whether a button is pressed or not.

Use the alternative-text attribute to describe the icon. The description should indicate what happens when you click the button, for example ‘Upload File’, not what the icon looks like, ‘Paperclip’.

The text is available to users in two ways.

• On the tooltip when you hover over the button
• As text for assistive technologies

Buttons that only show an icon to represent do not have an accessible name. For lightning-button-icon-stateful, provide the accessible name using the aria-label attribute.

Use the following accessibility and aria attributes on lightning-button-icon-stateful.

For more information, see the WAI-ARIA Specification.