Button Icon Stateful

lightning-button-icon-stateful

An icon-only button that retains state.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

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 and changes the state of the icon 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.

Handle the click event in your JavaScript code.

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

You can use a combination of the variant and size 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.

Visit utility icons in the SLDS 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.

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

Adjust the button and icon sizes 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 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-icon-stateful contains the same customizable elements as lightning-button, which supports --slds-c-button-* custom properties.

Custom properties for stateful button icons work only with particular lightning-button-icon-stateful variants.

CSS Custom Property	`lightning-button-icon-stateful` Variants
`--slds-c-button-color-background`	`border` (default) and `border-inverse`
`--slds-c-button-color-border`	N/A
`--slds-c-button-text-color`	N/A
`--slds-c-button-text-color-*`	`border` (default) and `border-filled`
`--slds-c-button-radius-border`	all
`--slds-c-button-sizing-border`	N/A

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.

Attribute	Type	Description
accesskey	string	A shortcut key to activate or place focus on the button
aria-atomic	boolean	Specifies whether the screen reader should always present the live region as a whole, even if only part of the region changes. The default is `false`.
aria-controls	ID reference list	An element ID or a space-separated list of element IDs whose presence or content is controlled by this button.
aria-describedby	ID reference list	An element ID or a space-separated list of element IDs that provide a descriptive label or description for the button.
aria-expanded	boolean	Indicates whether the state of an element, controlled by the button, is expanded or collapsed. To reference the controlled element, use `aria-controls`.
aria-label	string	Provides an assistive label where a visible label cannot be used.
aria-live	string	Indicates whether the button will be updated, and describes the types of updates assistive technologies will make. Possible values include `off`, `polite`, and `assertive`. The default is `off`. For the screen reader to announce changes when the user is idle, use `polite`. For immediate notifications, use `assertive`.

For more information, see the WAI-ARIA Specification.