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.

Choose a version:

Button

The button component triggers actions or events, such as submitting forms, opening dialogs, or navigating to other pages. Use buttons to let users perform specific tasks or initiate interactions throughout the interface.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Button component.

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:

Component Supported Actions Default ('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.

Component	Supported Actions	Default ('auto')
`ClipboardItem`	'copy'	'copy'

ButtonAccessibilityRole

The accessibility role for button-like components. - `button`: A generic button that triggers an action. - `submit`: A button that submits a form.

'button' | 'submit'

InlineAlignment

Controls how content is aligned along the inline axis (horizontal in standard writing modes). - `'start'`: Aligns content to the inline start of the container. - `'center'`: Centers content along the inline axis. - `'end'`: Aligns content to the inline end of the container.

'start' | 'center' | 'end'

Anchor to ExamplesExamples

Anchor to Add primary and secondary buttonsAdd primary and secondary buttons

Create a button that triggers an action when pressed. This example shows a primary button with an onPress handler.

Add primary and secondary buttons

Add primary and secondary buttons

import {

reactExtension,

Button,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

<Button

onPress={() => {

console.log('onPress event');

}}

Pay now

</Button>

);

}

import {extension, Button} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

const button = root.createComponent(

Button,

{onPress: () => console.log('onPress event')},

'Pay now',

);

root.appendChild(button);

});

React

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

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Button
      onPress={() => {
        console.log('onPress event');
      }}
    >
      Pay now
    </Button>
  );
}

JS

import {extension, Button} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const button = root.createComponent(
    Button,
    {onPress: () => console.log('onPress event')},
    'Pay now',
  );

  root.appendChild(button);
});

Anchor to Show a loading stateShow a loading state

Prevent duplicate submissions by showing a loading indicator while an operation completes. This example displays buttons with the loading prop across primary and secondary variants.

Show a loading state

import {

reactExtension,

Button,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

Saving...

</Button>

Applying...

</Button>

</>

);

}

import {extension, Button} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

const savingButton = root.createComponent(

Button,

{loading: true, kind: 'primary'},

'Saving...',

);

const applyingButton = root.createComponent(

Button,

{loading: true, kind: 'secondary'},

'Applying...',

);

root.appendChild(savingButton);

root.appendChild(applyingButton);

});

React

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

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <>
      <Button loading kind="primary">
        Saving...
      </Button>
      <Button loading kind="secondary">
        Applying...
      </Button>
    </>
  );
}

JS

import {extension, Button} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const savingButton = root.createComponent(
    Button,
    {loading: true, kind: 'primary'},
    'Saving...',
  );

  const applyingButton = root.createComponent(
    Button,
    {loading: true, kind: 'secondary'},
    'Applying...',
  );

  root.appendChild(savingButton);
  root.appendChild(applyingButton);
});

Anchor to Open an external pageOpen an external page

Navigate to an external page by using the to prop on a button. This example renders a button that links to an external URL.

Open an external page

import {

reactExtension,

Button,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

Visit our store

</Button>

);

}

import {extension, Button} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

const button = root.createComponent(

Button,

{to: 'https://www.shopify.com'},

'Visit our store',

);

root.appendChild(button);

});

React

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

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Button to="https://www.shopify.com">
      Visit our store
    </Button>
  );
}

JS

import {extension, Button} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const button = root.createComponent(
    Button,
    {to: 'https://www.shopify.com'},
    'Visit our store',
  );

  root.appendChild(button);
});

Anchor to Best practicesBest practices

Write action-oriented text: Clearly label each button to accurately represent the action. Use strong action verbs at the beginning of button text, such as "Add," "Save," or "Apply."
Choose appropriate emphasis: Use only one high-emphasis button (primary) per context. Use lower-emphasis buttons for secondary calls to action.
Use primary buttons for key actions: Reserve primary buttons for the most important action in a given flow, such as "Save" or "Apply." Use secondary buttons for alternatives like "Track your order."

Anchor to LimitationsLimitations

Buttons don't support custom widths. They size to their content or fill their container based on the layout.
When to is set, the button behaves as a link. Press event handlers are ignored.

Was this page helpful?