A button is used to trigger an action.

Or just an icon
This button is disabled. You can't use this button yet. Something has to finish loading first. Pretend you just used this button—something is loading now.
This isn't even every possible variation of button. Keep reading...

When to use

Buttons and links can get confused for one another, but they're not the same.

  • Buttons execute actions: showing content on the page that was previously hidden, playing a video, or submitting a form, and so on.
  • Links go to destinations: taking the user to a new page, or new section of the current page

For more about the differences between buttons and links, check out our Buttons and links pattern doc.

Button types

Role

Primary

This is the default role of a button.

Destructive

Destructive buttons are for an action that will permanently delete something from the system (e.g. deleting a benefits class).

Neutral

Neutral buttons are for secondary actions, or when none of the other roles apply. They don't have an outlined variant.

Inverse

Inverse buttons are for otherwise neutral use cases, when those don't meet WCAG minimum color contrast requirements. They don't have an outlined variant.

Variant

Filled

This is for only the highest-priority actions. There should only be one of these per page or section.

Outlined

For medium priority actions. Useful in a situation where you need a lot of buttons, like on a set of cards, and you want them to be noticeable, but not too overwhelming. Again, they only come in brand and destructive.

Ghost

For the lowest-priority actions. Great for button groups.

Size

Medium

The default. When in doubt, stick with it.

Small

for situations where the button needs to fit into a relatively small space, like as a list item or a toast.

Button states

Active

The default. When a button is active, you're able to interact with it.

OK, these buttons don't actually do anything. But the important thing is, they could.

Disabled

Disabled buttons can't be interacted with. They can be focused though, so that screen reader users know they're there, and so that all users can be shown a tooltip explaining what to do to enable the button.

There's no way to enable this button...but usually there would be. Sorry, this time you're stuck. This is just an example though. If this was real, this tooltip would explain how to enable this button.
Do
Don't
The second set of disabled buttons doesn't have any tooltips explaining what the user has to do to enable them.

Loading

Loading buttons also can't be interacted with, and have a spinner replacing their usual contents. They can be styled two different ways:

  • like disabled buttons, to indicate that the user can't interact with them yet
  • like pressed buttons, to indicate that the user has interacted with them, and the system is working on a response

Like disabled buttons, they can be focused, so that screen reader users know they're there, and so that all users can be shown a tooltip explaining what to do to enable the button.

Hang in there! This button will be available soon. Not so fast! We're still working on something on our end. Your patience is appreciated.
This sure is better than asking you not to click this button more than once. That's a lot of form data! We're gonna need a minute... Submitting your PTO request (just as one example)...

Button labels

Most of the time, your button is gonna need a text label. Here's some guidance for how to make those labels effective.

Do
  • Use sentence case
  • Start with a verb, then a noun: "Add employee", "Update PTO policy"
  • Use one-word labels, for commonly-accepted cases like "Done", "Close", or "Next"
Don't
  • Use ALL CAPS or Title Case
  • Include articles ("a", "an", or "the")
  • Use first-person pronouns. "Print your W-2", not "Print my W-2".
Avoid
  • Using more than 3 words in a button label. The harder it is to predict the outcome of activating the button, the less likely it is that users will try it.

Adding icons

Buttons can have icons added on the left, right, or in place of their text content.

For more about when and how to use icons in buttons, check out our Buttons and links pattern doc.

Or just an icon