buttons

Buttons are clickable items used to perform an action.

<button class="slds-button">Button</button>
<button class="slds-button slds-button_neutral">Neutral Button</button>
<button class="slds-button slds-button_brand">Brand Button</button>

About Buttons

Buttons should be used in situations where users might need to:

submit 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

Button vs. Link

The HTML elements for buttons and links describe a very specific type of action that is going to be taken when they are used. It is important you know when to use which, as the distinction matters:

Use a link when you’re navigating to another place, such as: a "view all" page, "Jane Chen" profile, a page "skip link" etc.
Use buttons when you are performing an action, such as: "submit," "merge," "create new," "upload," etc.
An action is almost always on the same page

Accessibility

If pressing a Button results in a new URL, or the resultant UI makes sense as "a new browser tab", that is a link <a>. Everything else is a <button>.

The distinction is important to screen reader users to know what's going to happen next. Will I navigate somewhere or will something happen on the page? So it's important to choose the right HTML element for the job.

If you absolutely cannot use a <button /> element for an action and instead need to use an <a />, you are required to do 2 things:

Add role="button" attribute to the <a /> to make the element announce itself as a button element.
Add a JavaScript event handler for when the user presses the space key. This is because a button element will respond by default to both the enter and space keys being pressed, but an <a /> element will not.

Finally, color alone does not suffice when conveying the meaning of buttons. Ensure that the text you use in the button matches 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.

Base Link Neutral Link Brand Link Outline Brand Link Destructive Link Text Destructive Link Success Link

<a class="slds-button" href="javascript:void(0);">Base Link</a>
<a class="slds-button slds-button_neutral" href="javascript:void(0);">Neutral Link</a>
<a class="slds-button slds-button_brand" href="javascript:void(0);">Brand Link</a>

Links that look like Buttons

Use these with caution - dictation software users may not be able to properly identify these actions, as they can say "show buttons" and these won't highlight since they are semantically links, even though they may look like buttons.

Mobile

On mobile devices, such as phones and other devices that have touch as the primary method of interaction, buttons will have an increased size to accommodate tapping with a finger instead of the more precise mouse cursor.
Below is a live example of what to expect in that context. No code changes are needed in the Salesforce platform context as this change occurs automatically in the appropriate context. For those users not on the Salesforce platform, these modifications will occur automatically when the secondary touch stylesheet is loaded and the device has touch as the primary method of interaction.

Select a device to set the width of the example

Base

The base slds-button looks like a plain text link. It removes all the styling of the native button.

The base and neutral buttons are used most frequently and can be used multiple times per feature. Use these buttons when the actions are of secondary importance to the content surrounding it, such as in the actions ribbon in a page header.

<button class="slds-button">Button</button>

Variations

Neutral

Add the slds-button_neutral class to create a neutral button.

<button class="slds-button slds-button_neutral">Neutral Button</button>

Brand

To create the brand button, add the slds-button_brand class to the slds-button class. The brand color tokens can be overridden for theme specific usage.

The Brand button generally should only be used once per component screen at any one time. It is used for when there is an action that is clearly more important than the other actions and you need to draw attention to it. An example is when you have a “Save” and “Cancel” button. The “Save” is the primary action.

Not all features need to have primary actions, sometimes the actions are secondary to the content and are all of equal importance.

<button class="slds-button slds-button_brand">Brand Button</button>

Outline Brand

To create the outline brand button, add the slds-button_outline-brand class to the slds-button class. The brand color tokens can be overridden for theme specific usage.

<button class="slds-button slds-button_outline-brand">Outline Brand Button</button>

Inverse

Use the inverse button on dark backgrounds. Add the slds-button_inverse class to the slds-button class.

<div style="background-color:#16325c;padding:0.5rem">
  <button class="slds-button slds-button_inverse">Inverse Button</button>
</div>

Destructive

To create the destructive button, add the slds-button_destructive class to the slds-button class.

This button is used to indicate a destructive action to the user, like permanently erasing data.

<button class="slds-button slds-button_destructive">Destructive Button</button>

Text Destructive

To create the text destructive button, add the slds-button_text-destructive class to the slds-button class.

This button is used to indicate a destructive action to the user, like permanently erasing data. Use this version when the Destructive button would be too distracting to the experience.

<button class="slds-button slds-button_text-destructive">Text Destructive Button</button>

Success

To create the success button, add the slds-button_success class to the slds-button class.

<button class="slds-button slds-button_success">Success Button</button>

Disabled

Use a disabled attribute when a button can’t be clicked. To create a disabled button, append the disabled attribute to the button.

<button class="slds-button" disabled="">Button</button>
<button class="slds-button slds-button_neutral" disabled="">Neutral Button</button>
<button class="slds-button slds-button_brand" disabled="">Brand Button</button>

With Icons

The SVG, element, or icon inside the button receives the slds-button__icon class. You can position the icon on the left or the right using slds-button__icon_left or slds-button__icon_right, which applies the correct amount of space between the icon and the text.

Left Icon

<button class="slds-button slds-button_neutral">
  <svg class="slds-button__icon slds-button__icon_left" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#download">

Mobile context changes
Please be aware that in a mobile context button icons will automatically change slightly as shown in the example below. For more details please see the mobile specific documentation above.

Select a device to set the width of the example

Right Icon

<button class="slds-button slds-button_neutral">Button Neutral<svg class="slds-button__icon slds-button__icon_right" aria-hidden="true">
    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#download">
    </use>

Stateful

Stateful buttons have three states: not selected (default), selected and focused, and selected with hover state.

The stateful button requires the slds-button_stateful class and the slds-button_neutral class in addition to the slds-button class. Stateful buttons are only used with the neutral variation.

The button contains three spans with classes that hide or show the content of the spans based on the class on the button. Each span contains text and a corresponding icon. The SVG will have the slds-button__icon_left class setting the icon on the left.

Accessibility Requirement
Be sure to include the attribute aria-live="assertive" on the button. The aria-live="assertive" attribute means the value of the <span> inside the button will be spoken whenever it changes.

JavaScript Requirement
When the user clicks the button, use JavaScript to toggle the class from slds-not-selected to slds-is-selected-clicked. As soon as focus leaves the button, use JavaScript to toggle the class from slds-is-selected-clicked to slds-is-selected.

Not Selected

Stateful button uses the class slds-not-selected in its initial state.

<button class="slds-button slds-button_neutral slds-button_stateful slds-not-selected" aria-live="assertive">
  <span class="slds-text-not-selected">
    <svg class="slds-button__icon slds-button__icon_small slds-button__icon_left" aria-hidden="true">

Selected and Focused

When selected and still focused, stateful button uses the class slds-is-selected-clicked.

<button class="slds-button slds-button_neutral slds-button_stateful slds-is-selected-clicked" aria-live="assertive">
  <span class="slds-text-not-selected">
    <svg class="slds-button__icon slds-button__icon_small slds-button__icon_left" aria-hidden="true">

Selected with Hover State

Once selected and blurred (user moved focus away from the button), stateful button uses the class slds-is-selected.

<button class="slds-button slds-button_neutral slds-button_stateful slds-is-selected" aria-live="assertive">
  <span class="slds-text-not-selected">
    <svg class="slds-button__icon slds-button__icon_small slds-button__icon_left" aria-hidden="true">

Dual Stateful Button

Dual Stateful buttons have two states, similar to a Toggle Button: not pressed (default), and pressed.

The Dual Stateful button requires the slds-button_dual-stateful class, along with a combination of the slds-button and slds-button_neutral classes. While Dual Stateful buttons are only used with the neutral Button variation, the pressed state changes the button style to that of the Brand variation.

The button contains two spans. Each span contains display text and a corresponding SVG icon with the class slds-button__icon-left and has classes that hide or show the contents. By default, the first span with the class slds-text-is-not-pressed is displayed; when the class slds-is-pressed is applied to the parent button, the span with the class slds-text-is-pressed is displayed.

Accessibility Requirement
Be sure to include the attribute aria-live="assertive" on the button. The aria-live="assertive" attribute means the value of the <span> inside the button will be spoken whenever it changes.

JavaScript Requirement
When the user clicks the button, use JavaScript to toggle the slds-is-pressed class on or off, depending on the previous state. Remember, only the pressed state requires this class.

Not Pressed

<button class="slds-button slds-button_neutral slds-button_dual-stateful" aria-live="assertive">
  <span class="slds-text-not-pressed">
    <svg class="slds-button__icon slds-button__icon_small slds-button__icon_left" aria-hidden="true">

Pressed

To display the pressed state, use the class slds-is-pressed on the <button> element.

<button class="slds-button slds-button_neutral slds-button_dual-stateful slds-is-pressed" aria-live="assertive">
  <span class="slds-text-not-pressed">
    <svg class="slds-button__icon slds-button__icon_small slds-button__icon_left" aria-hidden="true">

Sizing

Stretch

To allow the button's width to take up the entire width available, apply the slds-button_stretch class to the button.

<button class="slds-button slds-button_neutral slds-button_stretch">Stretched Neutral Button</button>

Full Width

Creates a full width button with styling resets

<button class="slds-button slds-button_neutral slds-button_full-width">Full Width Neutral Button</button>