Button

Buttons are used to make common actions immediately visible and easy to perform with one click, tap, or keypress. Merchants can use them to navigate or to take action.

Examples

Used most in the interface. Only use another style if a button requires more or less visual weight.

Drag to resize example

Props

accessibilityLabel
string
Visually hidden text for screen readers
ariaControls
string
Id of the element the button controls
ariaExpanded
boolean
Tells screen reader the controlled element is expanded
ariaPressed
boolean
Tells screen reader the element is pressed
children
string | string[]
The content to display inside the button
destructive
boolean
Indicates a dangerous or potentially negative action
disabled
boolean
Disables the button, disallowing merchant interaction
disclosure
boolean
Displays the button with a disclosure icon
download
string | boolean
Tells the browser to download the url instead of opening it. Provides a hint for the downloaded filename if it is a string value.
external
boolean
Forces url to open in a new tab
fullWidth
boolean
Allows the button to grow to the width of its container
icon
React.ReactNode | null | string | number | false | true | __type | ReactElement | ReactNodeArray | ReactPortal | FunctionComponent | SVGSource
Icon to display to the left of the button content
id
string
A unique identifier for the button
loading
boolean
Replaces button text with a spinner while a background action is being performed
monochrome
boolean
Makes `plain` and `outline` Button colors (text, borders, icons) the same as the current text color. Also adds an underline to `plain` Buttons
outline
boolean
Gives the button a subtle alternative to the default button styling, appropriate for certain backdrops
plain
boolean
Renders a button that looks like a link
primary
boolean
Provides extra visual weight and identifies the primary action in a set of buttons
size
"slim" | "medium" | "large"
Changes the size of the button, giving it more or less padding
submit
boolean
Allows the button to submit a form
url
string
A destination to link to, rendered in the href attribute of a link
onBlur
() => void
Callback when focus leaves button
onClick
() => void
Callback when clicked
onFocus
() => void
Callback when button becomes focussed
onKeyDown
(event: KeyboardEvent) => void
Callback when a keydown event is registered on the button
onKeyPress
(event: KeyboardEvent) => void
Callback when a keypress event is registered on the button
onKeyUp
(event: KeyboardEvent) => void
Callback when a keyup event is registered on the button

Accessibility

Buttons can have different states that are visually and programmatically conveyed to merchants.

  • Use the ariaControls prop to add an aria-controls attribute to the button. Use the attribute to point to the unique id of the content that the button manages.
  • If a button expands or collapses adjacent content, then use the ariaExpanded prop to add the aria-expanded attribute to the button. Set the value to convey the current expanded (true) or collapsed (false) state of the content.
  • Use the disabled prop to set the disabled state of the button. This prevents merchants from being able to interact with the button, and conveys its inactive state to assistive technologies.
  • Use the ariaPressed prop to add an aria-pressed attribute to the button.

Navigation

Merchants generally expect buttons to submit data or take action, and for links to navigate. If navigation is required for the button component, use the url prop. The control will output an anchor styled as a button, instead of a button in HTML, to help convey this difference.

For more information on making accessible links, see the link component.

Labeling

The accessibilityLabel prop adds an aria-label attribute to the button, which can be accessed by assistive technologies like screen readers. Typically, this label text replaces the visible text on the button for merchants who use assistive technology.

Use accessibilityLabel for a button if:

  • The button’s visible text doesn’t adequately convey the purpose of the button to non-visual merchants
  • The button has no text and relies on an icon alone to convey its purpose

To help support merchants who use speech activation software as well as sighted screen reader users, make sure that the aria-label text includes any button text that’s visible. Mismatches between visible and programmatic labeling can cause confusion, and might prevent voice recognition commands from working.

When possible, give the button visible text that clearly conveys its purpose without the use of accessibilityLabel. When no additional content is needed, duplicating the button text with accessibilityLabel isn’t necessary.

Do

<Button>Edit shipping address</Button>
<Heading>Shipping address</Heading>
<Button accessibilityLabel="Edit shipping address">Edit</Button>

Don’t

<Button accessibilityLabel="Change your shipping address">Edit</Button>
<Button accessibilityLabel="Edit">Edit</Button>

External links

When you use the button component to create a link to an external resource:

  • Use the external prop to make the link open in a new tab (or window, depending on the merchant’s browser settings)
  • Use the icon prop to add the external icon to the button
  • Use the accessibilityLabel prop to include the warning about opening a new tab in the button text for non-visual screen reader users

For more information on making accessible links, see the link component.

Do

<Button
  accessibilityLabel="Terms and conditions (opens a new window)"
  icon="external"
  url="http://example.com"
  external
>
  Terms and conditions
</Button>

Don’t

<Button url="http://example.com" external>Terms and conditions</Button>
<Button url="http://example.com" external>
  Terms and conditions
</Button>

Keyboard support

Buttons use browser defaults for keyboard interactions.

  • Give buttons keyboard focus with the tab key (or shift + tab when tabbing backwards)
  • Activate buttons with the enter/return key or the space key

Custom key events

Use the onKeyDown, onKeyPress, and onKeyUp props to create custom events for buttons. With these props, you can use buttons to create complex, custom interactions like drag-and-drop interfaces.

Since these props introduce non-standard features to buttons, make sure to include accessible instructions so that merchants can understand how to use these features.

Basic button

Used most in the interface. Only use another style if a button requires more or less visual weight.

Basic button for Android

Plain button

Use for less important or less commonly used actions since they’re less prominent. For example, plain buttons are used as actions in cards.

Plain button for Android

Primary button

Use to highlight the most important actions in any experience. Don’t use more than one primary button in a section or screen to avoid overwhelming merchants.

Primary button for Android

Destructive button

Use when the action will delete merchant data or be otherwise difficult to recover from. Destructive buttons should trigger a confirmation dialog before the action is completed. Be thoughtful about using destructive buttons because they can feel stressful for merchants.

Destrutive plain and destructive basic button for Android

Disabled state

Use for actions that aren’t currently available. The surrounding interface should make it clear why the button is disabled and what needs to be done to enable it.

Disabled primary button for Android

Accessibility

See Material Design and development documentation about accessibility for Android:

Basic button

Used most in the interface. Only use another style if a button requires more or less visual weight.

Basic button for iOS

Plain button

Use for less important or less commonly used actions since they’re less prominent. For example, plain buttons are used as actions in cards.

Plain button for iOS

Primary button

Use to highlight the most important actions in any experience. Don’t use more than one primary button in a section or screen to avoid overwhelming merchants.

Primary button for iOS

Destructive button

Use when the action will delete merchant data or be otherwise difficult to recover from. Destructive buttons should trigger a confirmation dialog before the action is completed. Be thoughtful about using destructive buttons because they can feel stressful for merchants.

Destrutive plain and destructive basic button for iOS

Disabled state

Use for actions that aren’t currently available. The surrounding interface should make it clear why the button is disabled and what needs to be done to enable it.

Disabled primary button for iOS

Accessibility

See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:

Best practices

Buttons should:

  • Be clearly and accurately labeled.
  • Lead with strong, actionable verbs.
  • Use established button colors appropriately. For example, only use a red button for an action that’s difficult or impossible to undo.
  • Prioritize the most important actions. Too many calls to action can cause confusion and make merchants unsure of what to do next.
  • Be positioned in consistent locations in the interface.

Content guidelines

Buttons should be clear and predictable—merchants should be able to anticipate what will happen when they click a button. Never deceive merchants by mislabeling a button.

Read the actionable language guidelines to learn what to label buttons for different states in web, iOS, and Android.

  • Create order

  • Buy shipping label

  • New order

  • Buy

Buttons should always lead with a strong verb that encourages action. To provide enough context to merchants use the {verb}+{noun} format on buttons except in the case of common actions like Save, Close, Cancel, or OK.

  • Activate Apple Pay

  • View shipping settings

  • Try Apple Pay

  • View your settings

Buttons should be scannable—avoid unnecessary words and articles such as the, an, or a.

  • Add menu item

  • Add a menu item