Button
The button component triggers actions or events, such as submitting forms, opening dialogs, or navigating to other pages. Use button 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. For grouping multiple related buttons, use button group.
Anchor to PropertiesProperties
Configure the following properties on the button component.
- booleanbooleanDefault: falseDefault: falserequiredrequired
Whether the button is disabled, preventing it from being clicked or receiving focus.
- requiredrequired
An icon displayed inside the button, typically positioned before the button text. Use icons to help users quickly identify the button's action or to improve scannability. Accepts any icon name from the icon library or a custom string identifier.
- booleanbooleanDefault: falseDefault: falserequiredrequired
Whether to replace the button content with a loading indicator while a background action is being performed.
This also disables the button component.
- "auto" | "primary" | "secondary" | "tertiary""auto" | "primary" | "secondary" | "tertiary"Default: 'auto'Default: 'auto'requiredrequired
The visual appearance of the button component.
auto: The variant is automatically determined by the button component's context.primary: High emphasis button for the primary action on the page. Should be used sparingly.secondary: Medium emphasis button for secondary actions.tertiary: Low emphasis button for less important actions.
- "critical" | "auto" | "neutral""critical" | "auto" | "neutral"Default: 'auto'Default: 'auto'requiredrequired
The semantic meaning and color treatment of the component.
critical: Urgent problems or destructive actions.auto: Automatically determined based on context.neutral: General information without specific intent.
- "auto" | AnyString | "_blank" | "_self" | "_parent" | "_top""auto" | AnyString | "_blank" | "_self" | "_parent" | "_top"Default: 'auto'Default: 'auto'requiredrequired
The browsing context where the linked URL should be displayed.
auto: The target is automatically determined based on the origin of the URL._blank: Opens the URL in a new window or tab._self: Opens the URL in the same browsing context as the current one._parent: Opens the URL in the parent browsing context of the current one. If there is no parent, behaves as_self._top: Opens the URL in the topmost browsing context (the highest ancestor of the current one). If there is no ancestor, behaves as_self.
- stringstringrequiredrequired
The URL to navigate to when clicked. The
clickevent fires first, then navigation occurs. Ifis also set, the command executes instead of navigation.- stringstringrequiredrequired
Prompts the browser to download the linked URL rather than navigate to it. When set, the value specifies the suggested filename for the downloaded file.
The filename suggestion is only respected for same-origin URLs,
blob:, anddata:schemes. Cross-origin URLs can still trigger downloads, but browsers might ignore the suggested filename.Learn more about the download attribute.
- "button" | "reset" | "submit""button" | "reset" | "submit"Default: 'button'Default: 'button'requiredrequired
The behavior of the button component.
button: Used to indicate the component acts as a button, meaning it has no default action.reset: Used to indicate the component acts as a reset button, meaning it resets the closest form (returning fields to their default values).submit: Used to indicate the component acts as a submit button, meaning it submits the closest form.
This property is ignored if the component supports
hrefor/commandand one of them is set.- stringstringrequiredrequired
A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey the component's purpose.
- '--auto' | '--show' | '--hide' | '--toggle''--auto' | '--show' | '--hide' | '--toggle'Default: '--auto'Default: '--auto'requiredrequired
The action that command should take when this component is activated.
--auto: A default action for the target component.--show: Shows the target component.--hide: Hides the target component.--toggle: Toggles the visibility of the target component.
- stringstringrequiredrequired
The component that commandFor should act on when this component is activated.
- stringstringrequiredrequired
The ID of the component to show when users hover over or focus on this component. Use this to connect interactive components to popovers or tooltips that provide additional context or information.
AnyString
A utility type that enables autocomplete for specific string literals while still accepting any string value. By intersecting `string` with an empty object type, this prevents TypeScript from widening literal types, preserving IDE suggestions for known values while maintaining flexibility for custom strings.
string & {}Anchor to EventsEvents
The button component provides event callbacks for handling user interactions. Learn more about handling events.
- CallbackEventListener<typeof tagName> | nullCallbackEventListener<typeof tagName> | nullrequiredrequired
A callback fired when the button loses focus.
Learn more about the blur event.
- CallbackEventListener<typeof tagName> | nullCallbackEventListener<typeof tagName> | nullrequiredrequired
A callback fired when the button is clicked.
Learn more about the click event.
- CallbackEventListener<typeof tagName> | nullCallbackEventListener<typeof tagName> | nullrequiredrequired
A callback fired when the button receives focus.
Learn more about the focus event.
CallbackEventListener
A function that handles events from UI components. This type represents an event listener callback that receives a `CallbackEvent` with a strongly-typed `currentTarget`. Use this for component event handlers like `click`, `focus`, `blur`, and other DOM events.
(EventListener & {
(event: CallbackEvent<T>): void;
}) | nullCallbackEvent
An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event. This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event.
Event & {
currentTarget: HTMLElementTagNameMap[T];
}Anchor to SlotsSlots
The button component supports slots for additional content placement within the component. Learn more about using slots.
- HTMLElementHTMLElement
The label text or elements displayed inside the button component, describing the action that will be performed when clicked.
Anchor to ExamplesExamples
Create a button with a text label to let merchants trigger an action. This example shows the basic button component with default styling.
Preview
html
Create buttons for actions like saving, creating, or navigating. This example shows primary and secondary buttons with clear, action-oriented labels.
Preview
html
Anchor to Set visual emphasis with variantsSet visual emphasis with variants
Use variants to establish a clear visual hierarchy between primary, secondary, and supplementary actions. This example shows all four variant options: primary, secondary, tertiary, and auto.
Preview
html
Anchor to Communicate intent with tonesCommunicate intent with tones
Apply tones to signal the purpose and potential impact of an action through color. This example shows critical tone for destructive actions, neutral tone for less prominent actions, and the default auto tone.
Preview
html
Anchor to Add an icon alongside a text labelAdd an icon alongside a text label
Combine an icon with a text label to help merchants identify what a button does. This example shows a button with both a text label and an icon to reinforce the action.
Preview
html
Create icon-only buttons to save space in dense interfaces like toolbars and action bars. This example shows multiple icon-only buttons with an accessibilityLabel for screen reader support.
Preview
html
Anchor to Show loading feedback during async operationsShow loading feedback during async operations
Add a loading state to prevent duplicate submissions and reassure merchants that an action is being processed. This example shows buttons with the loading prop across different variants.
Preview
html
Disable buttons to prevent interaction when prerequisites are not met, and set type to submit to integrate with HTML forms. This example shows a disabled button alongside a submit button.
Preview
html
Set the href property to make buttons navigate like links while maintaining button styling. This example shows internal navigation, opening external URLs in new tabs, and triggering file downloads.
Preview
html
Anchor to Confirm destructive actions with critical toneConfirm destructive actions with critical tone
Pair a cancel button with a critical-toned action button to help merchants avoid accidental destructive operations. This example shows a confirmation pattern for deleting a resource.
Preview
html
Anchor to Trigger actions on other componentsTrigger actions on other components
Use commandFor to connect a button to another component by ID, triggering built-in actions like toggling a popover or showing a modal. This example shows a button that opens a popover with a list of additional actions.
Preview
html
Anchor to Best practicesBest practices
- Label buttons clearly: Use strong, actionable verbs that clearly and accurately describe the action (like Save, Edit, or Add tags). Write labels in sentence case and avoid unnecessary words and articles (like a, an, the). Don't use punctuation.
- Use appropriate button tones: Apply established button tones appropriately. Use critical tone only for destructive actions that are difficult or impossible to undo. Match the tone to the action's impact and importance.
- Establish clear hierarchy: Prioritize the most important actions to avoid confusion. Use primary buttons for main actions, secondary buttons for supporting actions, and tertiary buttons for supplementary actions.
- Position consistently: Place buttons in consistent locations throughout the interface to create predictable interaction patterns.
- Icon-only buttons: For icon-only buttons, always use
accessibilityLabelto describe the action for screen reader users.
Anchor to LimitationsLimitations
- When using
hreffor navigation, external URLs (domains outside Shopify admin) might be blocked or show security warnings depending on the extension context and merchant's browser security settings. - Setting
loading={true}provides visual feedback and prevents form submission or multiple clicks. You must implement additional logic to debounce or disable the button action during async operations. - Icon-only buttons have a minimum touch target size but don't expand to fill available space. They maintain a fixed size based on the icon and padding, which might create layout inconsistencies if mixed with text buttons in the same container.
- Disabled buttons (
disabled={true}) are removed from the tab order and can't receive keyboard focus. If you disable a button temporarily (for example, while waiting for form validation), then provide visible text explaining why it's disabled. For async operations, useloadingoverdisabledbecauseloadingcommunicates that an action is in progress.