Skip to main content
BUTTONS

Button

Draft

Buttons are controls that let users take action, make choices, and move forward.

Color
Text

Common alternative names

Action, call to action, CTA

Principles​

Actionable​

A button label indicates what happens when the user taps the button, even if it's just to acknowledge something.

Contextual​

Buttons work with other elements on a screen to surface the most important actions the user wants to take in that context.

Incisive​

Buttons capture user intent concisely, distilling the action a user wants to take into an inclusive word or phrase.

Anatomy​

The most basic setup of a button includes only a single label or icon. Still, a button can also be customized to include a label with a leading icon and a trailing icon. Circle buttons can also support an additional label below the button's container.

Label (recommended)
Container (required)
Leading Icon (optional) · Trailing Icon (optional)

Shape​

Buttons come in rectangular, circle, square, and pill shapes.

Rect (default)

Rectangular buttons are typically used at fixed widths, 100% and 50% width on mobile, and a variety of widths on the web. Large rectangle buttons are commonly used CTA buttons that move users forward in a flow.

Circle

Circular buttons can include a text label or an icon. An optional label below is available as well. All maintain a center position.

Square

Square buttons, similar to circle buttons, can include a text label or an icon. All maintain a center position.

Pill

Pill buttons are more commonly in line with other content and controls.

Usage​

Use buttons to let users take action, make choices, and move forward. Buttons can navigate to other pages while completing an action like purchasing or submitting a form.

Hierarchy​

Button hierarchy emphasizes which button is more important in the context so the user can take action immediately.

Highest emphasis
primary container color
Medium emphasis
secondary container color
Low emphasis
transparent container color

Buttons use color and contrast to create three levels of emphasis and hierarchy. The buttons with the strongest emphasis are primary, followed by secondary, then tertiary.

HierarchyEmphasis# per contextUse for
PrimaryHigh1The most important action to move forward in a flow, acknowledge and dismiss, or finish a task.
SecondaryMediumManyMost actions are in line with other content.
TertiaryLowA fewDismissive actions give users a way out to cancel, do nothing, dismiss, or skip.

Primary​

Use one primary button per context to allow users to take a specific action, move forward in a flow, acknowledge and dismiss, or finish a task.

✓ Do

Use one primary button per context to highlight the action the user will most likely take.

✕ Don't

Avoid using multiple primary buttons on a screen.

Secondary​

Secondary buttons are the bread and butter of the button world. Lean into them whenever possible. The gray background protection provides higher visibility, making them more accessible than tertiary buttons.

✓ Do

Use secondary buttons inline with list items and other elements.

Avoid using primary buttons in the middle of the page
! Caution

Avoid using primary buttons in the middle of the page. Use secondary buttons instead. Primary actions usually should be pinned at the bottom.

Tertiary​

Tertiary buttons are mainly used for dismissive actions that give users a way out of something, letting them do nothing, dismiss, or skip.

✓ Do

Treat buttons with a dismissive behavior similar to "Cancel" with the tertiary style.

✕ Don't

Avoid using secondary-style buttons for dismissive actions.

Destructive buttons​

Destructive buttons are actions that permanently cause data loss. Because these actions can not be undone, using button hierarchy is essential to reduce errors. Two levels of destructive buttons are typically used together: secondary destructive and primary destructive.

Primary
Secondary
Tertiary
N/A

Provide additional friction to prevent user error

If a flow includes an action that could be destructive, it's important to give users a chance to double-check before it's completed. The initial action should be designed in a way that suggests caution, using a secondary destructive button, and then a final confirmation dialog should appear with a more obvious warning, using a primary destructive button.

✓ Do

Use standard buttons for actions that don't cause data loss.

✕ Don't

Don't use destructive actions for actions that don't cause data loss, like logging out or canceling a task.

Best practices​

Everything is a button​

In principle, try to think of the most actionable elements as buttons. Thinking and building this way ensures we have the right touch target areas and user feedback. It also makes our experiences easier to localize and friendlier for people using screen readers.

Avoid disabled buttons​

Disabled buttons can be confusing and frustrating for many users and can be difficult to spot for those with low vision. To make things easier, try to enable the button so users can tap it, and provide an error message if any information is missing or incorrect. If you must use a disabled button, include clarifying text, an error message, or a tooltip to explain why.

Leading icons convey meaning, trailing icons indicate affordance​

Use leading icons to reinforce the button label's meaning and trailing icons as an affordance of what will happen when you interact with the button.

Leading Icon
Reinforces meaning of label
♥ Favorites ▾
Trailing Icon
Affordance for what happens
after I interact, e.g. opens a menu

Common alternative names: Action, call to action, CTA

Behavior​

Touch targets​

All button sizes meet the minimum 28px touch target. The default (48px) and large (56px) sizes exceed the recommended 44px minimum for mobile. Use mini (28px) and compact (36px) only in dense desktop UI where touch is not the primary input.

States​

Primary​

Enabled

Text and icons: color-action-primary-text

Container: color-action-primary

Hover

Text and icons: color-action-primary-text

Container: color-action-primary + 10% white overlay

Focus

Text and icons: color-action-primary-text

Container: color-action-primary

Outline: 3 color-border-focus

Pressed / Mousedown

Text and icons: color-action-primary-text

Container: color-action-primary + 20% white overlay

N/a

Active

N/a

Disabled

Text and icons: color-text-disabled

Container: color-background-disabled

Loading

Spinner size matches icon size

Secondary​

Enabled

Text and icons: color-text-default

Container: color-action-secondary

Hover

Text and icons: color-text-default

Container: color-action-secondary + 4% black

Focus

Text and icons: color-text-default

Container: color-action-ghost-hover

Outline: 3 color-border-focus

Pressed / Mousedown

Text and icons: color-text-default

Container: color-action-secondary + 8% black overlay

Active

Text and icons: color-action-primary-text

Container: color-action-primary

Disabled

Text and icons: color-text-disabled

Container: color-background-disabled

Loading

Container: color-action-ghost-hover

Loading circle background: color-background-default

Loading circle complete: color-border-focus

Tertiary​

Enabled

Text and icons: color-text-default

Container: transparent

Hover

Text and icons: color-text-default

Container: color-action-ghost-hover

Focus

Text and icons: color-text-default

Container: transparent

Outline: 3 color-border-focus

Pressed / Mousedown

Text and icons: color-text-default

Container: 4% black overlay

Disabled

Text and icons: color-text-disabled

Container: transparent

Loading

Spinner: color-text-default

Width​

Our buttons come in two versions: Fixed and intrinsic width.

Fixed-width buttons have a width that matches the width of their container minus any space on either side. This is the fullWidth prop.

Intrinsic width buttons are sized according to the length of the text. Both versions support the addition of leading icons, but each version has slight differences in how the icons align.

Fixed-width (fill container)

If you enable icons for these buttons, the leading icon centers with the label, and the trailing icons pin to the end of the button (minus the spacing).

Button stretches to fill container width
"Fill container" in autolayout
Trailing icon aligned to right button edge (minus padding)
Leading icon centered with label

Intrinsic width (hug contents)

The button does not stretch to the container's width for intrinsic width buttons. The width equals the label's length plus spacing on either side. When icons are turned on for these buttons, the leading icon and trailing icons remain 8px from the label on either side.

container width
"Hug contents" in autolayout
button width = length of label + icon widths + padding

Pill button min-width

Rounded pill buttons have a minimum width to avoid that almost-circle look when fewer characters are in the label.

min width = button height + 24

4848
3636
✓ Do

Use the minimum width for buttons with shorter label lengths.

Buttons that are almost a pill but not quite a circle
✕ Don't

Don't use a width smaller than the minimum. This creates buttons that are almost a pill but not quite a circle.

Pill button max-width

Avoid stretching pill buttons to the width of a container. Use a rectangle button if you desire fixed-width behavior.

4 matched loads
Houston, TX to local, short hauls
✓ Do

Use intrinsic width pill buttons which correspond to the length of the label.

4 matched loads
Houston, TX to local, short hauls
✕ Don't

Avoid stretching pill buttons to fill the width of a container.

Wrapping and truncation​

Button stretches to fill container width
Label will wrap to the next line
Button stretches to fill container width
Label can truncate after a number of lines set

Fixed width buttons

Fixed-width buttons are configured to wrap to the following line by default, but they can be set to truncate to any number of lines if desired.

container width
Width will grow with the label and truncate at the end of the container

Intrinsic width buttons

Pill buttons hug the content inside them (intrinsic width). A pill button will keep growing with the length of the label until it reaches the edge of its layout. Beyond that, the button will start to truncate.

Buttons with longer labels set to intrinsic width have the potential to take over the layout, so it's essential to keep labels concise.

Breakpoints​

For fixed-width buttons, follow these breakpoint guidelines.

Narrow​

The button scales up in width until the screen reaches 600px wide.

375
⦿⦿⦿9:41 PM🔋
←
About us
We build interfaces that work for everyone
Good things happen when people can move, whether across town or toward their dreams. Opportunities appear, open up, become reality.
up to 600
⦿⦿⦿9:41 PM🔋
←
About us
We build interfaces that work for everyone
Good things happen when people can move, whether across town or toward their dreams. Opportunities appear, open up, become reality. What started as a way to tap a button to get a ride has led to billions of moments of human connection.

Wide​

For screens wider than 600px the Button will be in its original size and aligned to the leading side of the content.

600 and wider
⦿⦿⦿9:41 PM🔋
←
About us
We build interfaces that work for everyone
Good things happen when people can move, whether across town or toward their dreams. Opportunities appear, open up, become reality. What started as a way to tap a button to get a ride has led to billions of moments of human connection as people around the world go all kinds of places in all kinds of ways with the help of our technology.

Examples​

Narrow​

Wide​

  • ButtonGroup: Group of mutually exclusive buttons
  • ButtonDock: Fixed bottom action bar for primary or secondary actions
  • Link: For navigation without an action
  • Toggle: For binary on/off states
  • SegmentedControl: For switching between views