Button

A lightning-button component represents a button element that runs an action. Use lightning-button 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.

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 shows label text on the button. The title attribute provides tooltip text for the button.

Here's another example that creates a button with the brand variant, with a label and icon. The button places the icon to the left of the label by default, so the example uses icon-position to place the icon on the right.

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

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.

lightning-button implements the buttons blueprint in the Salesforce Lightning Design System (SLDS). The buttons adapt to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

Use a combination of icons, variants, and utility classes to customize your button styles.

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.

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 appears 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 appear.

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

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

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 by using lightning-button results in additional spacing next to the icon. To create a button that triggers a menu, use lightning-button-menu.

Icons aren’t available in Lightning Out, but they’re available in Lightning Components for Visualforce and other experiences.

If you're creating forms to interact with Salesforce records, consider lightning-record-form or lightning-record-edit-form instead of creating your own.

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 needs to meet the target size of 44x44 px. For more information, see Follow Accessible Mobile Design Guidelines.

Buttons must have an accessible name for assistive technology to announce the button's purpose. Provide this name by using the label attribute and make it a clear call to action, for example, "Edit record".

If you create an icon-only button with lightning-button, provide an accessible name by 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.

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

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

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’re trying to convey via color. For example, if you use the destructive button to point out a potential warning, make sure that the text communicates the same message.

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

Use these accessibility and aria attributes on lightning-button.

For more information, see the WAI-ARIA Specification.