Button

A lightning-button component represents a button element that executes an action. 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-record-edit-form 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-record-edit-form .

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

You can create a button with a label only, or add the icon-name attribute for a button with a label and icon. To create an icon-only button, use the lightning-button-icon component instead.

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<template>
2    <lightning-button
3        variant="brand"
4        label="Start"
5        title="Begins the task"
6        onclick={handleClick}
7    >
8    </lightning-button>
9</template>

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 icon-position to display it on the right.

1<template>
2    <lightning-button
3        variant="brand"
4        label="Download"
5        icon-name="utility:download"
6        icon-position="right"
7        onclick={handleClick}
8    >
9    </lightning-button>
10</template>

You can retrieve the button that's clicked by using event.target. For example, to retrieve the label on the button, use event.target.label.

lightning-button implements the buttons blueprint in the Salesforce Lightning Design System (SLDS).

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

The SLDS 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 lightning-button.

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

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

• 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 the color is used for the label and border only, not the button color.
• 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.

Buttons are animated by default. For the base variant, an underline is drawn when you mouse over the button. For the other variants, a ripple of contrasting color displays when you click the button.

When a button is disabled, the animation is disabled as well.

If your browser or operating system is set to reduce animation, the button animations don't display.

To prevent animation for a button, use the disable-animation attribute.

1<template>
2    <lightning-button
3        variant="brand"
4        label="Start"
5        title="Begins the task"
6        disable-animation
7        onclick={handleClick}>
8    </lightning-button>
9</template>

We recommend setting this attribute only when you place lightning-button near other buttons that aren't animated, for consistency.

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 using an SLDS class.

1<lightning-button label="Cancel" title="Cancel"></lightning-button>
2<lightning-button
3    variant="brand"
4    label="Brand"
5    title="Primary action"
6    class="slds-m-left_x-small"
7></lightning-button>

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

1<div>
2    <lightning-button
3        variant="brand"
4        label="Get Started"
5        title="Get Started"
6        stretch
7    ></lightning-button>
8</div>

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 supports these component styling hooks.

To create an icon-only button, use the lightning-button-icon 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-button-menu.

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-record-form or lightning-record-edit-form.

On mobile screens, we recommend setting the button size to 44x44 px. If you have more than one target on a screen that performs the same action, only one of the targets need to meet the target size of 44x44 px. For more information, see Follow Accessible Mobile Design Guidelines.

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 aria-label or aria-labelledby attribute. We recommend that you use one of the attributes but not both.

To provide a text label that's not visible on the screen, use aria-label.

1<lightning-button
2    aria-label="Download"
3    icon-name="utility:download"
4    variant="base"></lightning-button>

To associate the button with text from another element, use aria-labelledby.

1<h2 id="downloadLabel">Download Files</h2>
2<h3 id="downloadDesc">View and make changes to your files</h3>
3<lightning-button
4    aria-labelledby="downloadLabel downloadDesc"
5    icon-name="utility:download"
6    variant="base"></lightning-button>

To use aria-label with additional descriptive text, use aria-describedby.

1<lightning-button
2    aria-label="Close"
3    aria-describedby="descriptionClose"
4    icon-name="utility:close"
5    variant="base"></lightning-button>
6
7
8<div id="descriptionClose">Closing this window resets the form and
9returns you back to the main page.</div>

lightning-button provides many variants that add color to a button, which convey different meaning on a button. Use the variants together with clear text on the button to match the meaning you are trying to convey via color. For example, if you use the destructive button to point out a potential warning, make sure the text communicates the same message.

To inform screen readers that a button is disabled, include the disabled attribute.

Use the following accessibility and aria attributes on lightning-button.

For more information, see the WAI-ARIA Specification.