Button Icon

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

You can use a combination of the variant, size, class, and iconClass attributes to customize the button and icon styles. To customize styling on the button container, use the class attribute. For the bare variant, the size class applies to the icon itself. For non-bare variants, the size class applies to the button. To customize styling on the icon element, use the iconClass attribute. This example creates an icon-only button with bare variant and custom icon styling.

1<!-- Bare variant with custom "dark" CSS class added to icon svg element -->
2<lightning:buttonIcon
3  iconName="utility:settings"
4  variant="bare"
5  alternativeText="Settings"
6  iconClass="dark"
7/>

The Lightning Design System utility icon category offers nearly 200 utility icons that can be used in lightning:buttonIcon. Although the Lightning Design System provides several categories of icons, only the utility category can be used in lightning:buttonIcon.

Visit https://lightningdesignsystem.com/icons/#utility to view the utility icons.

When applying Lightning Design System classes or icons, check that they are available in the Lightning Design System release tied to your org. The latest Lightning Design System resources become available only when the new release is available in your org.

This component implements styling from button icons in the Lightning Design System.

Here is an example.

1<aura:component>
2  <lightning:buttonIcon
3    iconName="utility:close"
4    variant="bare"
5    onclick="{! c.handleClick }"
6    alternativeText="Close window"
7  />
8</aura:component>

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

When using lightning:buttonIcon in a standalone app, extend force:slds to resolve the icon resources correctly.

1<aura:application extends="force:slds">
2  <lightning:buttonIcon iconName="utility:close" alternativeText="Close" />
3</aura:application>

lightning:buttonIcon 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 alternativeText 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 alternativeText 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 alternativeText, 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 alternativeText.

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

.

1<lightning:buttonIcon
2  iconName="utility:settings"
3  title="Settings"
4  tooltip="Display your account settings"
5  alternativeText="Hidden text for assistive technology"
6>
7</lightning:buttonIcon>

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.

lightning:buttonIcon supports ARIA states and properties. For more information, see the Specification tab.