Button Icon

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

Here’s an example.

1<template>
2    <lightning-button-icon
3        icon-name="utility:close"
4        variant="bare"
5        onclick={handleClick}
6        alternative-text="Close window"
7    >
8    </lightning-button-icon>
9</template>

lightning-button-icon 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 the icon-class, size, variant, and class 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. icon-class supports SLDS utility classes only.

1<lightning-button-icon
2    icon-name="utility:settings"
3    variant="bare"
4    alternative-text="Settings"
5    icon-class="slds-m-around_medium"
6>
7</lightning-button-icon>

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

The SLDS utility icon category offers nearly 200 utility icons for use with lightning-button-icon. You can use only the utility category with lightning-button-icon.

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

• bare shows an icon without a container or border
• bare-inverse shows 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 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
• brand shows an icon in white color in a blue container with a blue border
• container shows 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 by 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 by using the slds-m-left_xx-small class.

1<lightning-button-icon
2    icon-name="utility:zoomin"
3    alternative-text="Zoom in"
4    title="Zoom in"
5></lightning-button-icon>
6<lightning-button-icon
7    icon-name="utility:zoomout"
8    alternative-text="Zoom out"
9    title="Zoom out"
10    class="slds-m-left_xx-small"
11></lightning-button-icon>

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

1<lightning-button-icon
2    icon-name="utility:zoomin"
3    alternative-text="Zoom in"
4    title="Zoom in"
5    class="my-round-button"
6></lightning-button-icon>

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.

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 specific lightning-button-icon variants.

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

Icons aren’t available in Lightning Out, but they’re 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 indicates 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 appears 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 show 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 makes sure 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’re 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.

1<lightning-button-icon
2    icon-name="utility:settings"
3    title="Settings"
4    tooltip="Display your account settings"
5    alternative-text="Hidden text for assistive technology"
6>
7</lightning-button-icon>

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

Buttons that show an icon instead of text don’t have an accessible name. To provide an accessible name in lightning-button-icon, use the aria-label attribute. If there’s visible text for the element, use aria-labelled-by instead.

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

Use these accessibility and aria attributes on lightning-button-icon.

For more information, see the WAI-ARIA Specification.