Button

Buttons are used to make common actions immediately visible and easy to perform with one click or tap. Merchants can use it to navigate, or 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
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
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 | SVGSource | "placeholder" | "add" | "alert" | "arrowDown" | "arrowLeft" | "arrowRight" | "arrowUp" | "arrowUpDown" | "calendar" | "cancel" | "cancelSmall" | "caretDown" | "caretUp" | "checkmark" | "chevronDown" | "chevronLeft" | "chevronRight" | "chevronUp" | "circleCancel" | "circleChevronDown" | "circleChevronLeft" | "circleChevronRight" | "circleChevronUp" | "circleInformation" | "circlePlus" | "conversation" | "delete" | "disable" | "dispute" | "duplicate" | "embed" | "export" | "external" | "help" | "horizontalDots" | "import" | "notes" | "notification" | "print" | "refresh" | "risk" | "save" | "search" | "subtract" | "view"
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
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

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

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

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