Inline components

Render MoonPay frames declaratively inside your own layout.

Every MoonPay frame has a corresponding React component you can render directly in your JSX tree. You control placement, sizing, and animation — the component mounts the frame where you put it.

Declarative vs imperative

The SDK exposes two ways to present a frame:

• Inline components — you render <MoonPayBuyButton />, <MoonPayWidget />, etc. inside your own layout. The frame appears where the element sits in the tree.
• Client methods — you call client.setupWidget(), client.setupAddCard(), etc. The provider presents the frame in a full-screen modal that it manages for you.

You can mix both approaches in the same app. Inline components are a good fit when you want the frame embedded in a custom screen. Client methods are convenient when a full-screen presentation is acceptable.

All components must be rendered inside a <MoonPayProvider>.

The quote prop

The quote prop on <MoonPayBuyButton> and the other payment components accepts a quote signature string from client.getQuote(). This prop is reactive: when you update it, the SDK pushes the new signature directly into the live frame via setQuote without remounting or reloading. With headless, the frame reads a new quote only after an "error" with code quoteExpired.

const [quoteSignature, setQuoteSignature] = React.useState(initialSignature);

// Later, after re-quoting:
setQuoteSignature(newQuote.signature);

// The frame receives the update without a remount.
<MoonPayBuyButton quote={quoteSignature} onEvent={handleEvent} />;

All other props — theme, url, externalTransactionId, headless — are mount-time only. Changing them after the component mounts causes the frame to remount.

Headless components

These components render nothing visible (0×0) and exist for API uniformity — they are the declarative alternatives to their imperative counterparts:

Component	Imperative equivalent
<MoonPayConnectionCheck>	client.getConnection()
<MoonPayBuyButton headless>	client.setupBuy() (deprecated)
<MoonPayConnectionReset>	client.resetConnection()

Results from these components arrive through their onEvent callback.

Component reference

Component	Description
<MoonPayBuyButton>	Inline Apple Pay, Google Pay, or card buy button, or a headless purchase with headless. quote is reactive.
<MoonPayConnect>	Inline connect flow. Credentials applied on active completion.
<MoonPayAuth>	Inline auth (email/OTP). Requires clientToken in context.
<MoonPayWidget>	Inline buy widget. quote is mount-time only.
<MoonPayChallenge>	Inline 3DS/challenge frame. Mount when a payment frame emits challenge.
<MoonPayAddCard>	Inline card entry frame.
<MoonPayConnectionCheck>	Headless — checks connection status.
<MoonPayConnectionReset>	Headless — resets the customer’s connection.

Deprecated components

These components still work, but new integrations render <MoonPayBuyButton> instead.

Component	Replacement
<MoonPayApplePayButton>	<MoonPayBuyButton>
<MoonPayGooglePayButton>	<MoonPayBuyButton>
<MoonPayBuyFrame>	<MoonPayBuyButton headless>