---
title: Button
description: >-
  The button component triggers actions or events, such as submitting forms,
  opening dialogs, or navigating to other pages. Use buttons to let buyers
  perform specific tasks or initiate interactions.
api_version: 2026-04
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/button
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/button.md
---

# Button

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

Buttons support various visual styles, tones, and interaction patterns to communicate intent and hierarchy. They can also function as links, guiding buyers to internal or external destinations. For navigation-focused interactions within text, use [link](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link). For grouping multiple related buttons, use [button group](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/button-group).

### Support Targets (29)

### Supported targets

* [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target)
* [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target)
* [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets)
* [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-)
* [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target)
* [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets)
* [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target)
* [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target)
* [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-)
* [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets)
* [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets)
* [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target)
* [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets)
* [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target)
* [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets)
* [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-)
* [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target)
* [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target)
* [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target)

#### Use cases

* **Primary actions**: Progress buyers through checkout with actions like "Pay now" or "Continue to shipping."
* **Secondary actions**: Provide supporting actions such as "Cancel," "Edit," or "Apply discount" alongside a primary action.
* **Loading states**: Display loading indicators during asynchronous operations like payment processing while preventing duplicate submissions.
* **Link-style navigation**: Navigate to external pages or resources using a button with `href`, when a more prominent affordance than an inline link is needed.

***

## Properties

Configure the following properties on the button component.

* **accessibilityLabel**

  **string**

  A label that describes the purpose or content of the button for users of assistive technologies such as screen readers. Use this when the visible content alone doesn't provide enough context.

* **command**

  **'--auto' | '--show' | '--hide' | '--toggle' | '--copy'**

  **Default: '--auto'**

  Sets the action the `commandFor` target should take when this component is activated. Available options:

  * `'--auto'`: Performs the default action appropriate for the target component.
  * `'--show'`: Displays the target component if it's currently hidden.
  * `'--hide'`: Conceals the target component from view.
  * `'--toggle'`: Alternates the target component between visible and hidden states.
  * `'--copy'`: Copies the target clipboard item.

  The supported actions vary by target component type. Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).

* **commandFor**

  **string**

  The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).

  When both `commandFor` and `href` are set, `commandFor` takes precedence. The command runs and the link doesn't navigate.

* **disabled**

  **boolean**

  **Default: false**

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

* **href**

  **string**

  The URL to navigate to when clicked. The `click` event fires first, then navigation occurs. If `commandFor` is also set, the command executes instead of navigation.

* **id**

  **string**

  A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.

* **inlineSize**

  **'auto' | 'fill' | 'fit-content'**

  **Default: 'auto'**

  The inline width of the button component.

  * `'auto'`: The size depends on the surface and context.
  * `'fill'`: The button takes up 100% of the available inline size.
  * `'fit-content'`: The button takes up the minimum inline size required to fit its content.

* **interestFor**

  **string**

  The ID of the component to show when users hover over or focus on this component. Pair with a target component that supports interest-based interactions. Learn more about the [interestFor attribute](https://open-ui.org/components/interest-invokers.explainer/#the-pitch-in-code).

* **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.

* **target**

  **'auto' | '\_blank'**

  **Default: 'auto'**

  Specifies where to display the linked URL. Learn more about the [target attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).

  * `'auto'`: Opens the URL in the current frame or a new tab, depending on the context.
  * `'_blank'`: Opens the URL in a new tab or window.

* **tone**

  **'auto' | 'neutral' | 'critical'**

  **Default: 'auto'**

  The semantic meaning and color treatment of the button.

  * `'auto'`: Automatically determined based on context.
  * `'neutral'`: General information without specific intent.
  * `'critical'`: Urgent problems or destructive actions.

* **type**

  **'submit' | 'button'**

  **Default: 'button'**

  The behavioral type of the button component, which determines what action it performs when activated.

  * `submit`: Submits the nearest containing form.
  * `button`: Performs no default action, relying on the `click` event handler for behavior.

  This property is ignored if `href` or `commandFor`/`command` is set.

* **variant**

  **'auto' | 'primary' | 'secondary'**

  **Default: 'auto'**

  The visual style variant of the button component, which controls its prominence and emphasis.

  * `'auto'`: Automatically determined by the button's context.
  * `'primary'`: High-emphasis style for the main action.
  * `'secondary'`: Medium-emphasis style for supporting actions.
  * `'tertiary'`: Low-emphasis style for less prominent actions.

### Events

The button component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events).

* **click**

  **CallbackEventListener\<typeof tagName>**

  A callback fired when the button is clicked. This will be called before the action indicated by `type`.

  Learn more about the [click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event).

### CallbackEventListener

A typed event listener for custom element events. The listener receives a \`CallbackEvent\` with the correct \`currentTarget\` type for the associated custom element tag.

```ts
(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): void;
}) | null
```

### CallbackEvent

An event type that narrows the \`currentTarget\` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

```ts
TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}
```

***

## Examples

### Add primary and secondary buttons

Create a save and cancel button pair to highlight the primary action. This example shows two `s-button` elements with `variant` set to `primary` and `secondary`.

## Add primary and secondary buttons

![A rendered example of the button component](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/button-default-BNP27v3f.png)

## html

```html
<s-button variant="secondary">Cancel</s-button>
<s-button variant="primary">Save</s-button>
```

### Show a loading state

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

## html

```html
<!-- Payment processing -->
<s-button loading variant="primary">Placing order...</s-button>


<!-- Discount validation -->
<s-button loading variant="secondary">Applying code...</s-button>
```

### Open an external page

Navigate to an external page by adding the `href` attribute to a button. This example renders an `s-button` with `href` and `target="_blank"` to open the destination in a new tab.

## html

```html
<s-button href="https://www.shopify.com" target="_blank">Visit our store</s-button>
```

***

## Best practices

* **Write action-oriented text**: Use specific, actionable language like "Apply discount" or "Save preferences" rather than vague terms like "OK" or "Click here."
* **Choose appropriate variants**: Use `primary` for the main action and `secondary` for supporting actions. Limit each context to one primary button.
* **Show loading states**: Set `loading` to `true` during async operations to prevent duplicate submissions and provide visual feedback.
* **Structure hierarchies clearly**: Group related actions together. Use `tone="critical"` for destructive actions to prevent accidental activation.

***