---
schema_version: "1"
id: 3e46c007c43fca14cd339792e2a44efe282c28a084ca4694935e0fec58f2f65b
title: Button Icon
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/buttonIcon/lightning-button-icon.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-button-icon.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 43f24446a662e2fe370c32b5416f437791f8817e2f41cd89a5d83cf88e41fbb7
products:
- Lightning Component Reference
---
# Button Icon
**`lightning-button-icon`**
A button that contains only an icon.
**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="buttonIcon" model="lwc" namespace="lightning"}
:::::
:::::tab
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.
```html
```
## Design
`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.
| | SLDS 1 | SLDS 2 |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design** | [Button Icons](https://v1.lightningdesignsystem.com/components/button-icons/) | [Button Icons](https://www.lightningdesignsystem.com/components/button-icons/) |
| **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 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.
```html
```
### 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) offers nearly 200 utility
icons for use with `lightning-button-icon`. You can use only the utility category with `lightning-button-icon`.
**note:** When applying SLDS classes or icons, check that they’re
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.
- `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.
### Sizes
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
### Utility Classes
To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) 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.
```html
```
To apply custom styling, use the `:host` selector or define a custom class by using the `class` attribute.
```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-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.
| CSS Custom Property | `lightning-button-icon` Variants |
| ---------------------------------- | ------------------------------------------------------------ |
| `--slds-c-button-color-background` | `border` (default), `bare`, `bare-inverse`, and `container` |
| `--slds-c-button-color-border` | `bare`, `bare-inverse`, and `container` |
| `--slds-c-button-text-color` | N/A |
| `--slds-c-button-text-color-*` | `border` (default), `bare`, `container`, and `border-filled` |
| `--slds-c-button-radius-border` | all |
| `--slds-c-button-sizing-border` | `bare`, `bare-inverse`, `border-inverse`, and `container` |
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
Icons aren’t available in Lightning Out, but they’re available in Lightning Components for Visualforce and other experiences.
## Accessibility
`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.
```html
```
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`.
| Attribute | Type | Description |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| accesskey | string | A shortcut key to activate or place focus on the button. |
| aria-atomic | boolean | Specifies whether the screen reader always presents 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 descriptive labels for the button. |
| aria-expanded | boolean | Indicates whether a collapsible element that's controlled by the button is expanded or collapsed. To reference the controlled element, use `aria-controls`. |
| aria-haspopup | token | Indicates that the button has an interactive popup element. Valid values are 'true', 'dialog', 'menu', 'listbox', 'tree', and 'grid'. To create a button that displays a list of menu items when clicked, use `lightning-button-menu` instead. |
| aria-label | string | Provides an assistive label where a visible label can’t be used. |
| aria-live | token | Indicates that the button can dynamically update without a page reload, and specifies how the change is announced by assistive technologies. 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`. |
| tabindex | integer | Specifies whether the button is focusable during tab navigation. Set the tab index to -1 to prevent focus on the button during tab navigation. The default value is 0, which makes the button focusable during tab navigation. For more information, see [tabindex](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex). |
For more information, see the [WAI-ARIA Specification](https://www.w3.org/TR/wai-aria/).
:::::
:::::tab
::component-specification{component="buttonIcon" model="lwc" namespace="lightning"}
:::::
::::::