Shop Pay button
The ShopPayButton component renders a Shop Pay button that checks out a selected variant right away or checks out the current cart. Use the component in React and Vue apps.
For DOM code, server-rendered HTML, and frameworks without a Hydrogen binding, use createShopPayButton, renderShopPayButton, and defineShopPayButton from @shopify/hydrogen.
Import ShopPayButton from @shopify/hydrogen/react or @shopify/hydrogen/vue.
Anchor to PropertiesProperties
Props for the component. The props match the options of . The component doesn't accept or style props.
- Anchor to accessibilityLabelaccessibility
Labelaccessibility Label stringstring Localized accessible label for the button. Defaults to
"Buy with Shop Pay". Keep the brand name Shop Pay untranslated and in Latin script in every locale.- Anchor to borderRadiusborder
Radiusborder Radius stringstring CSS border radius of the button, such as
8px. Defaults to12px.Pass a single CSS value. The Shop Pay functions throw an error when the radius contains a semicolon or a curly brace.
- Anchor to channelchannelchannel'headless' | 'hydrogen''headless' | 'hydrogen'
Sales channel that the checkout URL carries as
channel. Omit the channel unless checkout needs explicitheadlessorhydrogenattribution.- Anchor to checkoutUrlcheckout
Urlcheckout Url stringstring Absolute checkout base URL. Omit the URL to link to the same-origin
/checkoutand/cartpermalink paths, which Hydrogen's Shopify route handler redirects to the store's checkout.Pass the cart's checkout URL when your app doesn't send same-origin checkout paths through the Shopify route handler. The button URL keeps the query params of the checkout URL, replaces any params that Shop Pay sets, and drops the hash. A bare domain such as
my-store.myshopify.comgets an HTTPS scheme. The Shop Pay functions throw an error when the value isn't a valid URL.- Anchor to disableddisableddisabledbooleanboolean
Disables the button. A disabled button renders without an
hrefand witharia-disabled="true".- Anchor to noncenoncenoncestringstring
Content Security Policy nonce for the button's style element.
The nonce covers only the style element. Custom width and border radius values render as an inline style attribute, which a strict Content Security Policy must allow.
- Anchor to paymentOptionpayment
Optionpayment Option 'shop_pay' | 'shop_pay_installments''shop_pay' | 'shop_pay_installments' Checkout payment mode. Defaults to
. Useto open Shop Pay Installments at checkout.- Anchor to sourcesourcesourcestringstring
Attribution source that the checkout URL carries as
source. Defaults tohydrogen. Most storefronts shouldn't change the source.- Anchor to sourceTokensource
Tokensource Token stringstring Attribution token that the checkout URL carries as
.- Anchor to variantsvariantsvariantsShopPayVariantsShopPayVariants
Variants that the customer buys right away through a Shopify cart permalink. Omit the variants to check out the current cart.
Pass either all variant ID strings or all objects with an
idand an optionalquantity. Each quantity must be a positive integer. The Shop Pay functions throw an error for product IDs, non-numeric variant IDs, invalid quantities, and mixed formats.- Anchor to widthwidthwidthstringstring
CSS width of the button, such as
100%. Defaults to260px.Pass a single CSS value. The Shop Pay functions throw an error when the width contains a semicolon or a curly brace.
ShopPayVariants
Variants for a Shop Pay checkout, as all ID strings or all objects with an ID and a quantity.
readonly string[] | readonly ShopPayVariantWithQuantity[]ShopPayVariantWithQuantity
A variant ID and an optional quantity for a Shop Pay checkout.
- id
Product variant GID or numeric variant ID. Product IDs throw an error.
string - quantity
Quantity of the variant. Defaults to `1`.
number
React
Examples
Description
Render the button next to a React product form. This example renders nothing until a variant resolves and passes the quantity and disabled state.
React
import { ShopPayButton } from "@shopify/hydrogen/react"; type BuyNowProps = { variantId: string | null; quantity: number; disabled: boolean; }; export function BuyNow({ variantId, quantity, disabled }: BuyNowProps) { if (!variantId) return null; return ( <ShopPayButton variants={[{ id: variantId, quantity }]} disabled={disabled} width="100%" borderRadius="9999px" /> ); }Description
Render the button next to a Vue product form. This example uses `v-if` to wait for a resolved variant and binds the quantity and disabled state.
Vue
<script setup lang="ts"> import { ShopPayButton } from "@shopify/hydrogen/vue"; defineProps<{ variantId: string | null; quantity: number; disabled: boolean; }>(); </script> <template> <ShopPayButton v-if="variantId" :variants="[{ id: variantId, quantity }]" :disabled="disabled" width="100%" border-radius="9999px" /> </template>
Anchor to Browser elementBrowser element
Creates a Shop Pay button element in the browser. Append the element to the page.
The function requires a DOM. Use during server rendering.
Anchor to createShopPayButton-parametersParameters
- ShopPayButtonOptionsShopPayButtonOptionsrequiredrequired
The variants, checkout URL, and display settings for the button.
The Shop Pay button element, ready to append to the page.
ShopPayButtonOptions
Checkout target, variants, attribution, and display settings for a Shop Pay button.
- accessibilityLabel
Localized accessible label for the button. Defaults to `"Buy with Shop Pay"`. Keep the brand name Shop Pay untranslated and in Latin script in every locale.
string - borderRadius
CSS border radius of the button, such as `8px`. Defaults to `12px`. Pass a single CSS value. The Shop Pay functions throw an error when the radius contains a semicolon or a curly brace.
string - channel
Sales channel that the checkout URL carries as `channel`. Omit the channel unless checkout needs explicit `headless` or `hydrogen` attribution.
'headless' | 'hydrogen' - checkoutUrl
Absolute checkout base URL. Omit the URL to link to the same-origin `/checkout` and `/cart` permalink paths, which Hydrogen's Shopify route handler redirects to the store's checkout. Pass the cart's checkout URL when your app doesn't send same-origin checkout paths through the Shopify route handler. The button URL keeps the query params of the checkout URL, replaces any params that Shop Pay sets, and drops the hash. A bare domain such as `my-store.myshopify.com` gets an HTTPS scheme. The Shop Pay functions throw an error when the value isn't a valid URL.
string - disabled
Disables the button. A disabled button renders without an `href` and with `aria-disabled="true"`.
boolean - nonce
Content Security Policy nonce for the button's style element. The nonce covers only the style element. Custom width and border radius values render as an inline style attribute, which a strict Content Security Policy must allow.
string - paymentOption
Checkout payment mode. Defaults to `shop_pay`. Use `shop_pay_installments` to open Shop Pay Installments at checkout.
'shop_pay' | 'shop_pay_installments' - source
Attribution source that the checkout URL carries as `source`. Defaults to `hydrogen`. Most storefronts shouldn't change the source.
string - sourceToken
Attribution token that the checkout URL carries as `source_token`.
string - variants
Variants that the customer buys right away through a Shopify cart permalink. Omit the variants to check out the current cart. Pass either all variant ID strings or all objects with an `id` and an optional `quantity`. Each quantity must be a positive integer. The Shop Pay functions throw an error for product IDs, non-numeric variant IDs, invalid quantities, and mixed formats.
ShopPayVariants - width
CSS width of the button, such as `100%`. Defaults to `260px`. Pass a single CSS value. The Shop Pay functions throw an error when the width contains a semicolon or a curly brace.
string
TypeScript
Examples
Description
Create a full-width Shop Pay button for a variant and quantity. This example appends the button to a container and returns it.
TypeScript
import { createShopPayButton } from "@shopify/hydrogen"; export function mountShopPayButton(container: HTMLElement, variantId: string, quantity: number) { const button = createShopPayButton({ variants: [{ id: variantId, quantity }], width: "100%", }); container.append(button); return button; }
Anchor to Server HTML and custom elementServer HTML and custom element
Returns the Shop Pay button as an HTML string for server templates and frameworks without a Hydrogen binding.
On the server, the markup includes the button's styles and link, and the button works without client JavaScript. In the browser, the function returns an empty element that renders the button when you add the element to the page.
Anchor to renderShopPayButton-parametersParameters
- ShopPayButtonOptionsShopPayButtonOptionsrequiredrequired
The variants, checkout URL, and display settings for the button.
Anchor to renderShopPayButton-returnsReturnsstringstring
The Shop Pay button markup.
Anchor to defineShopPayButtondefine
Registers the Shop Pay button custom element in the browser. Call the function when you use the hydrogen-shop-pay-button tag directly on a framework without a Hydrogen binding.
The Hydrogen Shop Pay components, , and register the element for you. The function does nothing during server rendering or when the browser already has the element.
Anchor to defineShopPayButton-returnsReturnsvoidvoid
Nothing.
TypeScript
Examples
Description
Render a product buy button as an HTML string. This example disables the button while a mutation is pending and wraps it in surrounding markup.
TypeScript
import { renderShopPayButton } from "@shopify/hydrogen"; export function renderBuyNow(variantId: string, quantity: number, pending: boolean) { const shopPay = renderShopPayButton({ variants: [{ id: variantId, quantity }], disabled: pending, width: "100%", borderRadius: "9999px", }); return `<div class="buy-buttons">${shopPay}</div>`; }
Anchor to StylingStyling
The Shop Pay button is a hydrogen-shop-pay-button custom element that holds the link and logo in a shadow root. Page CSS can't reach the shadow root. Size the button with the width and borderRadius options.