When Button text does not provide sufficient context about the Button’s behavior, supply a short, descriptive label for screen-readers using
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
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.
Be sure to localize
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.
Button is available in 3 fixed sizes. The Button text has always a fixed size of 16px:
Large is the only size that should be used on Pinner surfaces.
Medium is used on more dense UI such as business surfaces or internal tools.
Small should be used sparingly and only in places where the UI is very dense.
- 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.
- Full-width (
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.
Color on white backgrounds
- Red (Primary)
High emphasis, used for primary actions.
- Blue (Primary in shopping context)
The blue Button is only intended for the shopping experience and is used for primary shopping actions.
- Gray (Secondary)
Medium emphasis, used for secondary actions.
- 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 on color/image backgrounds
- White (Primary)
High emphasis when placed on color/image backgrounds, used for primary actions in that context.
- Semi-transparent white (Secondary)
Medium emphasis when placed on color/image backgrounds, used for secondary actions in that context.
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.
- Button (default)
roleis used for actions. This is the default and should be used for most Buttons.
roleis used for navigating by URL. These Buttons should not use a
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.
The typical state of a Button that represents it can be interacted with and is not in a selected state.
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.
When Button is used to toggle a boolean state or control the visibility of other elements (e.g. Dropdown), use the
selectedprop to indicate the current state. Do not use this prop with
Accessibility props: controls, expanded, & popup
To control focus or position anchored components relative to Button, use
ref as shown in the example below.
When displaying multiple Buttons in a layout, use ButtonGroup to ensure consistent spacing and wrapping behavior.
Use IconButton when only an icon is needed instead of text.
Use TapArea to make non-button elements interactive, like an Image. This ensures the element interaction is accessible and uses Gestalt styles.
Tabs are intended for page-level navigation between multiple URLs.
OnLinkNavigationProvider allows external link navigation control across all children components with link behavior.
See OnLinkNavigationProvider to learn more about link navigation.