Button

A lightning:button component represents a button element that executes an action in a controller. Use lightning:button where users need to:

• submit or reset a form
• begin a new task
• trigger a new UI element to appear on the page
• specify a new or next step in a process

Use the type attribute to specify button, submit, or reset. The default type is button and doesn’t need to be specified.

The submit and reset types create buttons for submitting and resetting form data. Use these button types in lightning:recordEditForm and the HTML form element. The reset type button only deletes the values in the form fields without interacting with the database. For information about resetting the form fields to their initial values, see lightning:recordEditForm.

For the default button, clicking the button triggers the click event. Use an onclick handler to perform the button’s action.

Use the variant and class attributes to apply additional styling.

• base is a button without a border, which gives it the look of a plain text link.
• neutral is the default variant, a plain uncolored button.
• brand is a blue button, used to draw attention to the primary action on a page.
• brand-outline is similar to brand but only the label and border are blue.
• destructive is a red button used to warn users that its action has a negative effect.
• destructive-text is similar to destructive but only the label and border are red.
• inverse uses the background color and light text, useful for dark backgrounds.
• success is a green button used to indicate a successful action.

You can also apply utility classes with the class attribute.

You can create a button with a label only, or add the iconName attribute for a button with a label and icon. For an icon-only button, use lightning:buttonIcon instead.

You can also set the stretch attribute to true to expand the button to the full available width. In this example, the button stretches horizontally to fit the full <div> container.

1<aura:component>
2  <div>
3    <lightning:button
4      variant="brand"
5      label="Get Started"
6      stretch="true"
7      onclick="{! c.handleClick }"
8    />
9  </div>
10</aura:component>

The Lightning Design System utility icon category provides nearly 200 utility icons that can be used in lightning:button along with label text. Although SLDS provides several categories of icons, only the utility category can be used in this component.

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

This component implements styling from buttons in the Lightning Design System.

Here’s an example that creates a button with the brand variant, and displays label text on the button. The title attribute provides tooltip text for the button.

1<aura:component>
2  <lightning:button
3    variant="brand"
4    label="Submit"
5    onclick="{! c.handleClick }"
6  />
7</aura:component>

Here’s another example that creates a button with the brand variant, with a label and icon. The icon is positioned to the left of the label by default, so the example uses iconPosition to display it on the right.

1<aura:component>
2  <lightning:button
3    variant="brand"
4    label="Download"
5    iconName="utility:download"
6    iconPosition="right"
7    onclick="{! c.handleClick }"
8  />
9</aura:component>

You can retrieve the button that’s clicked by using event.getSource(). For example, to retrieve the label on the button, use event.getSource().get("v.label").

To create an icon-only button, use the lightning:buttonIcon component instead. Creating an icon-only button using lightning:button results in additional spacing next to the icon. To create a button that triggers a menu, use lightning:buttonMenu.

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

If you’re creating forms to interact with Salesforce records, consider using lightning:recordForm or lightning:recordEditForm.

Buttons must have an accessible name to enable assistive technology to describe the button’s purpose. Provide this name using the label attribute and make it a clear call to action, for example, “Edit record”.

If you create an icon-only button using lightning-button, provide an accessible name using the ariaLabel attribute, which provides a text label that’s not visible on the screen.

1<aura:component>
2  <lightning:button aria-label="Download" iconName="utility:download" />
3</aura:component>

To use ariaLabel with additional descriptive text, use ariaDescribedBy.

1<lightning:button
2  ariaLabel="Close"
3  ariaDescribedBy="descriptionClose"
4  iconName="utility:close"
5  variant="base"
6/>
7
8<div id="descriptionClose">
9  Closing this window resets the form and returns you back to the main page.
10</div>

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

lightning:button supports some aria attributes for accessibility. See the Specifications tab.

For more information, see the WAI-ARIA Specification.