Button Icon

A lightning-button-icon component represents an icon-only button element that executes an action in a controller. Clicking the button triggers the JavaScript method set for onclick.

Here is an example.

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

You can use a combination of the icon-class, size, and variant attributes to customize the button and icon styles.

To customize styling on the icon element, use the icon-class attribute. This example creates an icon-only button with bare variant and icon styling. Only SLDS utility classes are currently supported with icon-class.

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. Although SLDS provides several categories of icons, only the utility category can be used in lightning-button-icon.

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.

• bare displays an icon without a container or border
• bare-inverse displays an icon in white color without a container or border, useful for dark backgrounds
• 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
• brand displays an icon in white color in a blue container with a blue border
• container displays an icon in a transparent container without a border

For the bare and bare-inverse variants, the size class applies to the icon itself. For all other variants, the size class applies to the button.

Add the disabled attribute to prevent interaction with the button icon.

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

For bare and bare-inverse variants:

• medium is the default size, which creates a 14px by 14px icon
• small creates a 12px by 12px icon
• x-small creates a 8px by 8px icon
• large creates a 24px by 24px icon

For other variants:

• 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 the slds-m-left_xx-small class.

To apply custom styling, use the :host selector or define a custom class using the class attribute.

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 contains the same customizable elements as lightning-button, which supports --slds-c-button-* custom properties. Custom properties for button icons work only with particular lightning-button-icon 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 contains an informational icon, which conveys information that surrounding text doesn't. For each icon, provide assistive text that describes the button's action.

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 description you provide to alternative-text is available to users in two ways.

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

To override the hover text provided by alternative-text, use the title attribute, which corresponds to the native browser tooltip. The description you provide to title displays when you hover over the button. To support touch-only devices, keyboard navigation, and assistive technologies, use title together with label or alternative-text.

To display a contextual popup on the button, use the tooltip attribute. The popup becomes visible when you hover over the button, or after the button receives keyboard focus. Showing the popup on hover or on keyboard focus ensures that all users can access it, even if they aren’t using a mouse. The button is rendered with aria-describedby, linking it to the ID of the popup, which helps assistive technology read the popup content.

If you use both title and tooltip attributes, they are both visible when you hover over the button. Some screen readers don’t support the title attribute and many of them don’t read the title attribute by default.

For sighted users, make sure your description on title and tooltip are not repetitive. We recommend providing detailed information to tooltip and make title more concise if you use both.

Buttons that display an icon instead of text do not have an accessible name. To provide an accessible name in lightning-button-icon, use the aria-label attribute. If there is visible text labeling the element, use aria-labelled-by instead.

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

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

For more information, see the WAI-ARIA Specification.