lightning:buttonIcon

An icon-only HTML button.

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.

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

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.

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

Here is an example.

<aura:component>
    <lightning:buttonIcon iconName="utility:close" variant="bare" onclick="{! c.handleClick }" alternativeText="Close window." />
</aura:component>
Usage Considerations

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

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

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'.

Methods

This component supports the following method.

focus(): Sets the focus on the element.

Attributes

Attribute Name Attribute Type Description Required?
accesskey String Specifies a shortcut key to activate or focus an element.
alternativeText String The alternative text used to describe the icon. This text should describe what happens when you click the button, for example 'Upload File', not what the icon looks like, 'Paperclip'. Yes
body Component[] The body of the component. In markup, this is everything in the body of the tag.
class String A CSS class for the outer element, in addition to the component's base classes.
disabled Boolean Specifies whether this button should be displayed in a disabled state. Disabled buttons can't be clicked. This value defaults to false.
iconClass String The class to be applied to the contained icon element.
iconName String The Lightning Design System name of the icon. Names are written in the format '\utility:down\' where 'utility' is the category, and 'down' is the specific icon to be displayed. Note: Only utility icons can be used in this component. Yes
name String The name for the button element. This value is optional and can be used to identify the button in a callback.
onblur Action The action triggered when the element releases focus.
onclick Action The action that will be run when the button is clicked.
onfocus Action The action triggered when the element receives focus.
size String The size of the buttonIcon. For the bare variant, options include x-small, small, medium, and large. For non-bare variants, options include xx-small, x-small, small, and medium. This value defaults to medium.
tabindex Integer Specifies the tab order of an element (when the tab button is used for navigating).
title String Displays tooltip text when the mouse moves over the element.
type String Specifies the type of button. Valid values are button, reset, and submit. This value defaults to button.
value String The value for the button element. This value is optional and can be used when submitting a form.
variant String The variant changes the appearance of buttonIcon. Accepted variants include bare, container, border, border-filled, bare-inverse, and border-inverse. This value defaults to border.