Buttons allow users to perform actions within a surface. They can be used alone for immediate action, or as a trigger for another component, like Dropdown or Popover.

Props

Component props
Name
Type
Default
text
Required
string
-

Text to render inside the Button to convey the function and purpose of the Button.

accessibilityControls
string
-

A unique id indicating the element or elements whose contents or visibility are controlled by Button. See the Accessibility guidelines to learn more.

accessibilityExpanded
boolean
-

Needed if Button controls the visibility of other elements, e.g. Dropdown or Flyout. This is used to indicate if the controlled grouping is currently expanded or collapsed. See the Accessibility guidelines to learn more.

accessibilityHaspopup
boolean
-

Set as true if Button controls one or more interactive popup elements, such as a menu or dialog. See the Accessibility guidelines to learn more.

accessibilityLabel
string
-

Label to provide more context around Button’s function or purpose. See the Accessibility guidelines to learn more.

color
"gray" | "red" | "blue" | "transparent" | "semiTransparentWhite" | "transparentWhiteText" | "white"
"gray"

The background color of Button.

disabled
boolean
-

Indicates if Button is disabled. Disabled Buttons are inactive and cannot be interacted with.

fullWidth
boolean
false

Default Buttons are sized by the text within the Button whereas full-width Buttons expand to the full width of their container.

href
string
-

Specifies a link URL. Required with role="link" Buttons.

iconEnd
$Keys<typeof icons>
false

An icon displayed after the text to help clarify the usage of Button.

onClick
({ event: SyntheticMouseEvent<HTMLButtonElement> | SyntheticKeyboardEvent<HTMLButtonElement> | SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement>, {| dangerouslyDisableOnNavigation: () => void |}> }) => void
-

Callback invoked when the user clicks (press and release) on Button with the mouse or keyboard. Required with role="button" or type="button" Buttons.

See OnLinkNavigationProvider to learn more about link navigation.

ref
React.Ref<"button"> | React.Ref<"a">
-

A React ref to forward to the underlying element.

rel
"none" | "nofollow"
"none"

Optional with link-role Buttons.

role
"button" | "link"
"button"

Use “link” to indicate Button that is acting as an <a> link.

selected
boolean
false

Indicates if Button is currently selected.

size
"sm" | "md" | "lg"
"md"

sm: 32px, md: 40px, lg: 48px

tabIndex
-1 | 0
0

Use "-1" to remove Button from keyboard navigation. See the Accessibility guidelines to learn more.

target
null | "self" | "blank"
"null"

Indicates the browsing context where an href will be opened. Optional with role="link" Buttons.

type
"submit" | "button"
"button"

Use “submit” if Button is used within or associated with a form.

Usage guidelines

When to use
  • Communicating an action that will occur.
  • Triggering or enabling an action, such as submitting requested information.
  • Progressing or regressing a user through a step in a flow.
When not to use
  • Directing users to a new page or different part within the same page. Instead, use Link.
  • Limited space available. Consider using an IconButton instead.

Best practices

Do

Place primary Buttons to the right or top of other Button styles.

Don't

Place more than one primary Button per container/area.

Do

Show the full text on Buttons. Buttons should be stacked when they cannot be displayed side by side.

Don't

Truncate the Button text. In rare instances where Buttons must remain on one line, truncate the text on the secondary Button before truncating on the primary Button.

Do

Keep the Button text as simple and actionable as possible. Refer to the Button writing guidelines for more detail. If text is not sufficient for accessibility, refer to Accessibility guidelines for more detail.

Don't

Do not add icons to a Button to reinforce the text.

Do

Use an IconButton + Tooltip next to the disabled Button if you need to explain why it is disabled.

Accessibility

ARIA attributes

When Button text does not provide sufficient context about the Button’s behavior, supply a short, descriptive label for screen-readers using accessibilityLabel.
Texts like “Click here“, “Follow“, or “Shop“ can be confusing when a screen reader reads them out of context. In those cases, we must pass an alternative text with deeper context to replace the Button text, like “Follow Ryan” or “Shop Wedding Invitations”.

If Button is used as a control Button to show/hide a Popover-based component, we recommend passing the following ARIA attributes to assist screen readers:

  • accessibilityLabel: if present, read by screen readers read instead of the text prop.
  • accessibilityControls: informs the screen reader that Button controls the display of an anchored Popover-based component. It populates aria-controls.
  • accessibilityHaspopup: informs the screen reader that there’s a Popover-based component attached to Button. It populates aria-haspopup.
  • accessibilityExpanded: informs the screen reader whether the button-anchored Popover-based component is currently open or closed. It populates aria-expanded.

Localization

Be sure to localize text and accessibilityLabel. Note that localization can lengthen text by 20 to 30 percent. Avoid truncating Button text whenever possible. Refer to the Button usage guidelines for more information.

Variants

Size

Button is available in 3 fixed sizes. The Button text has always a fixed size of 16px:

  1. lg (48px)
    Large is the only size that should be used on Pinner surfaces.
  2. md (40px)
    Medium is used on more dense UI such as business surfaces or internal tools.
  3. sm (32px)
    Small should be used sparingly and only in places where the UI is very dense.
size="sm"
size="md"
size="lg"

Width

  1. Inline (default)
    Inline is our default Button width. The width of an inline Button is based on the length of its text. Use in most cases where you need a Button.
  2. Full-width (fullWidth)
    Full-width Buttons can be used in narrower content areas when the text in the Button is close to full width in the content area. This is especially common to see in components such as Callout and Upsell at their smaller breakpoints.
false
fullwidth

Color on white backgrounds

  1. Red (Primary)
    High emphasis, used for primary actions.
  2. Blue (Primary in shopping context)
    The blue Button is only intended for the shopping experience and is used for primary shopping actions.
  3. Gray (Secondary)
    Medium emphasis, used for secondary actions.
  4. Transparent (Tertiary)
    Low emphasis when placed on dark/image backgrounds, used for tertiary actions in that context. Note, this treatment should be used with caution as it has potential color contrast issues.
color="red"
color="blue"
color="gray"
color="transparent"

Color on color/image backgrounds

  1. White (Primary)
    High emphasis when placed on color/image backgrounds, used for primary actions in that context.
  2. Semi-transparent white (Secondary)
    Medium emphasis when placed on color/image backgrounds, used for secondary actions in that context.

Icons

Icon end
Adds an icon after the Button text. Icons should only be used to visually reinforce a specific function or interaction of the Button. Menus and external links are a common use case. Use arrow-up-right when linking to an external URL or arrow-down when displaying a Popover on click. Note that iconEnd on Button is not accessible to screen readers.

Role

  1. Button (default)
    The “button” role is used for actions. This is the default and should be used for most Buttons.
  2. Link
    The “link” role is used for navigating by URL. These Buttons should not use a selected state.

rel and target

These optional props control the behavior of role="link" Buttons. External links commonly use target="_blank" to open the link in a new tab or window, and rel="nofollow" to provide hints for SEO.

States

  1. Default
    The typical state of a Button that represents it can be interacted with and is not in a selected state.
  2. Disabled
    Used to block user interaction such as hover, focus and click. Disabled Buttons are completely unreachable by a keyboard and screenreader, so do not attach Tooltips to disabled Buttons.
  3. Selected
    When Button is used to toggle a boolean state or control the visibility of other elements (e.g. Dropdown), use the selected prop to indicate the current state. Do not use this prop with role="link" Buttons.

Accessibility props: controls, expanded, & popup

Ref

To control focus or position anchored components relative to Button, use ref as shown in the example below.

Writing

Do
  • If your object is already described on the screen, Buttons only need a verb (Example: Save).
  • If your object isn’t described on the screen, Buttons need a verb + the object (Example: Create Pin).
  • Use fewer than 3 words.
  • Use sentence case.
Don't
  • Do not use punctuation.

ButtonGroup
When displaying multiple Buttons in a layout, use ButtonGroup to ensure consistent spacing and wrapping behavior.

IconButton
Use IconButton when only an icon is needed instead of text.

TapArea
Use TapArea to make non-button elements interactive, like an Image. This ensures the element interaction is accessible and uses Gestalt styles.

Tabs
Tabs are intended for page-level navigation between multiple URLs.

OnLinkNavigationProvider
OnLinkNavigationProvider allows external link navigation control across all children components with link behavior.
See OnLinkNavigationProvider to learn more about link navigation.