Button Preview

Resources

Types

Button

A standard button initiates a single action or event.

Split button

A split button lets someone take one of several related actions. The dominant action is the button label and additional actions are tucked away in a menu. The dominant action should not be repeated in the menu.

Menu button

A menu button toggles the display of a menu of options. Unlike the split button, the menu button does not surface a primary action.

Compound button

A compound button includes a main title and an additional description of the title. Use it when it’s helpful to include more detail.

Behavior

Toggle button

A toggle button is a two-state behavior that switches a state between on and off. A button’s rest state indicates “off” while the selected state indicates “on.” The button and compound button types can have toggle behavior.

Toggle buttons are typically used in toolbars. In other scenarios like a settings panel, use a switch to let someone choose between two mutually exclusive options and trigger an immediate change.

To display toggle behavior, manipulate a button’s state properties. In the code, use the ToggleButton component and pass the checked prop.

Layout

Only use one primary button in a layout for the most important action. If there are more than two buttons with equal priority, all buttons should have neutral backgrounds.

When there are many available minor actions, use the outline, subtle, or transparent appearances on all buttons to avoid a busy layout.

Give primary buttons prominence

Don’t give secondary actions the same visual weight

Always give the primary button action prominent placement, either on top of or to the left of other actions. In right-to-left languages, primary button placement will be on the right.

Accessibility

Toggle button actions and states

Toggle buttons communicate two pieces of complementary information—the current status of a component and what happens when someone interacts with the component. When possible, use text as well as a change in visible indicator, like a change in icon or color, to convey both pieces of information.

Give context that communicates both state and action

Color contrast on buttons

To ensure buttons are visually accessible, any button text must pass 4.5:1 and icons must pass 3:1 contrast against their background in all interactive states. As long as text and icons within buttons meet the contrast requirement, there’s no contrast requirement for the button stroke.

Disabled buttons aren’t interactive and don’t need to pass color contrast.

Tooltips and ARIA labels

For disabled buttons, show a tooltip that states what is unavailable and why, and/or how to gain access to it.

For split buttons where part of the primary button label is not repeated in the secondary button options, include the skipped words in aria-describedby labels to make sure the meaning of each option is accessible to screen readers.

For example, in a split button that says New message as the primary button label, and just Event as the visible label for secondary option (without the word New), use New event as aria-describedby for that menu option.

Content

In general, use active language that reflects the action that will happen next. Be brief, usually a single verb is best but include a noun if it increases clarity. Use sentence case and no end punctuation.

Buttons that add or create

When someone can create something new, in most cases, use the button label “New”, followed by the name of the thing that they can create. For example, “New solution,” or “New mail.”

On a menu button

On a menu button where multiple options are available within a menu, use the button label “New”. Labels for the options in the menu should skip New, and just state the name of the new thing, like “Message,” or “Event.”

On a split button

On a split button, which displays a primary action in the rest state, use the full phrase in that primary action label, as well as in each of the other options. The primary action should not be repeated in the list of secondary options.

When adding or moving an existing item to a new place, use the button label Add followed by the type of existing item. For example, “Add agents” or “Add people.”

Whenever possible, buttons respond to titles

In secondary surfaces with title slots, like dialogs and drawers, write button labels that are specific responses to the main information in the title for the task. For example, the title “Delete this file?” should have buttons labeled “Delete” and “Cancel.”

Moving through multistep flows

In multistep flows with dedicated surfaces, like wizards or carousels, use “Next” (not Continue) for the button that advances to the next step. To give the user the option to move backwards, use “Previous” (not Back).

Buttons to end a task: Done, Finish, Close, Got it, and Dismiss

Use “Done” on the final screen of multi-step flows that only requires user acknowledgement. The Next button changes to Done on the last screen of the flow.

Use “Finish” when the options you select during the task are only committed by expressly selecting a button.

For an informational message that is not an error, and has no call to action, use “Close.”

In error messages, don’t use OK as a button label to dismiss the message. Use “Close” instead, which avoids implying that the error is acceptable.

Don’t confuse Close with Cancel.

• Use “Cancel” to stop a task in progress, close the surface the task is running on, if applicable, and return to the previous state without saving changes.
• Use “Close” when closing a dialog, drawer, or window, with no effect on the state of the task in progress. This is also the standard tooltip label for the “X” button. Don’t use the “X” button in combination with a Close button.

Use “Got it” to indicate that it’s important to read the content before closing. These are usually helpful when telling uses about new apps or features and are used mostly in teaching popovers and FREs.

Use “Dismiss” when this button not ony closes the surface, but also prevents it from popping up again later with a reminder. To make this more explicit, it might be helpful to provide a checkbox for “Don’t show this again.”

Apply versus Save

In ideal experiences, changes users make save automatically so they don’t have to worry about losing data. If autosave functionality isn’t possible, give users the option to expressly save their changes. Use the button label Save to signal to users they can commit their changes. Make sure to include success or error signals to let users know whether their changes have been committed or not. Message bars and confirmation toasts work well in these scenarios.