Button Preview
A button triggers a single action or event.
Use buttons for important actions like submitting a response, committing a change, or moving to the next step. For navigating to another place, try a link instead.
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.
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.
Content
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.
Common patterns for buttons
When someone can create something new, always use “New.” On a standard button, include the name of the thing they can create. On a menu button, the label will only be “New” and the action options in the menu should include “New” plus the thing to create, like “New message” or “New event.”
When someone can add something that already exists, always use “Add.” On a standard button, include the name of the thing they can create. On a menu button, the label will only be “Add” and the action options in the menu should include “Add” plus the thing to create, like “Add member” or “Add channel.”
