Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Button

Buttons are used for actions, such as “Add”, “Continue”, “Apply”, or “Save”.

Support
Targets (50)

Supported targets

Anchor to ButtonPropsButtonProps

Anchor to accessibilityLabel
accessibilityLabel
string

A label that describes the purpose or content of the button for users of assistive technologies such as screen readers. When set, any children supplied to this component won't be announced to screen reader users.

Anchor to accessibilityRole
accessibilityRole
Default: 'button'

The role of the button that will be rendered.

  • 'button': Renders a regular button.
  • 'submit': Renders a button that submits a form.
Anchor to activateAction
activateAction
'auto' | 'copy'
Default: 'auto' - a default action for the target component.

Sets the action the activateTarget should take when this component is activated.

Supported actions by component:

ComponentSupported ActionsDefault ('auto')
ClipboardItem'copy''copy'
Anchor to activateTarget
activateTarget
string

The ID of the component to control when this component is activated. Pair with the activateAction property to specify what action to perform on the target component.

Anchor to appearance
appearance
'critical' | 'monochrome'

The semantic meaning and color treatment of the button, such as 'critical' for destructive actions or 'monochrome' for a neutral appearance.

Anchor to disabled
disabled
boolean
Default: false

Whether the button is disabled, preventing it from being activated or receiving focus.

Anchor to id
id
string

A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.

Anchor to inlineAlignment
inlineAlignment
Default: 'center'

Specifies the inline alignment of the content.

Anchor to kind
kind
'primary' | 'secondary' | 'plain'
Default: 'primary'

The visual style variant of the button, which controls its prominence and emphasis. The visual presentation is controlled through the Branding API.

  • 'primary': High-emphasis style for main actions, such as "Continue to next step."
  • 'secondary': Medium-emphasis style for secondary actions that don't block user progress, such as "Download Shop app."
  • 'plain': Renders the button with a link-like appearance.
Anchor to loading
loading
boolean
Default: false

Whether the button is in a loading state, which replaces the button content with a loading indicator while a background action is being performed. This also disables the button.

Anchor to loadingLabel
loadingLabel
string

Accessible label for the loading indicator when user prefers reduced motion. This value is only used if loading is true.

Anchor to onPress
onPress
() => void

A callback fired when the button is activated by the user.

Anchor to overlay
overlay
RemoteFragment

An overlay component to render when the user interacts with the component, such as a popover, modal, or tooltip.

Anchor to to
to
string

The URL to navigate to when the button is activated. The onPress callback fires first, then navigation occurs.

Anchor to toggles
toggles
string

The ID of the component whose visibility will be toggled when this component is activated. Use this to show or hide related content like a disclosure panel.

Anchor to submit
submit
boolean

Whether the button submits the nearest containing form when activated.

Deprecated

Use accessibilityRole="submit" instead.

Anchor to ExamplesExamples

Anchor to Basic ButtonBasic Button

Basic Button

Example

Basic Button

import {
reactExtension,
Button,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return (
<Button
onPress={() => {
console.log('onPress event');
}}
>
Pay now
</Button>
);
}
import {extension, Button} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const button = root.createComponent(
Button,
{onPress: () => console.log('onPress event')},
'Pay now',
);

root.appendChild(button);
});

Anchor to AppearanceAppearance

ValueDescription
"critical"Conveys a problem has arisen.
"monochrome"Takes the color of its parent.

Anchor to Best PracticesBest Practices

Content best practices

  • Clearly label each button to accurately represent the action associated with it.

  • Use strong actionable verbs at the beginning of button text to make it clear to the buyer what action occurs when the button is clicked.

Hierarchy best practices

  • Establish a visual hierarchy between buttons to minimize confusion and help buyers understand which actions are most important.

  • Use only one high-emphasis button (primary button) per context to make it clear that other buttons have less importance.

  • Use lower-emphasis buttons for secondary calls to action.

  • Use primary buttons for concluding an action in a modal such as “Apply” or for key extension actions like “Add gift message.”

  • Use secondary buttons to provide alternative actions to the primary button, without disrupting the primary flow such as “Track your order”.

  • Use plain buttons for least prominent, non-critical actions such as “Login to your account”.

When to use buttons

  • Use buttons to communicate actions the buyer can take.

  • Use buttons to allow buyers to interact with the page.

When not to use buttons

  • Don’t use buttons as navigational elements. Use links instead when the desired action is to take the buyer to a new page.

Anchor to RelatedRelated

ComponentLink
Was this page helpful?