---
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 users
  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
  users to internal or external destinations. For navigation-focused
  interactions within text, use
  [link](/docs/api/checkout-ui-extensions/2026-04/web-components/actions/link).
  For grouping multiple related buttons, use [button
  group](/docs/api/checkout-ui-extensions/2026-04/web-components/actions/button-group).
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 users 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 users to internal or external destinations. For navigation-focused interactions within text, use [link](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/link). For grouping multiple related buttons, use [button group](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/button-group).

### Support Targets (29)

### Supported targets

* purchase.​checkout.​actions.​render-before
* purchase.​checkout.​block.​render
* purchase.​checkout.​cart-line-item.​render-after
* purchase.​checkout.​cart-line-list.​render-after
* purchase.​checkout.​contact.​render-after
* purchase.​checkout.​delivery-address.​render-after
* purchase.​checkout.​delivery-address.​render-before
* purchase.​checkout.​footer.​render-after
* purchase.​checkout.​header.​render-after
* purchase.​checkout.​payment-method-list.​render-after
* purchase.​checkout.​payment-method-list.​render-before
* purchase.​checkout.​pickup-location-list.​render-after
* purchase.​checkout.​pickup-location-list.​render-before
* purchase.​checkout.​pickup-location-option-item.​render-after
* purchase.​checkout.​pickup-point-list.​render-after
* purchase.​checkout.​pickup-point-list.​render-before
* purchase.​checkout.​reductions.​render-after
* purchase.​checkout.​reductions.​render-before
* purchase.​checkout.​shipping-option-item.​details.​render
* purchase.​checkout.​shipping-option-item.​render-after
* purchase.​checkout.​shipping-option-list.​render-after
* purchase.​checkout.​shipping-option-list.​render-before
* purchase.​thank-you.​announcement.​render
* purchase.​thank-you.​block.​render
* purchase.​thank-you.​cart-line-item.​render-after
* purchase.​thank-you.​cart-line-list.​render-after
* purchase.​thank-you.​customer-information.​render-after
* purchase.​thank-you.​footer.​render-after
* purchase.​thank-you.​header.​render-after

## Properties

* **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 [`command`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) 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.

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

* **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.
  * `'reset'`: Resets all fields in the nearest containing form to their default values.

  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

Learn more about [registering events](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/using-polaris-components#event-handling).

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

## Preview

![](https://cdn.shopify.com/shopifycloud/shopify-dev/development/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/button-default-BNP27v3f.png)

### Examples

* #### Code

  ##### Default

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

## Best 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 user what action will occur when the button is clicked.

**Hierarchy Best Practices**

* Establish a visual hierarchy between buttons to minimize confusion and help users 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 actions that progress users through checkout such as “Pay now” or for concluding an action in a modal such as “Apply”.

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

**When to Use Buttons**

* Use buttons to communicate actions the user can take.

* Use buttons to allow users 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 user to a new page.