Main component

<primer-main>

Optional container that provides structured slots for payment methods, checkout completion, and initialization errors. Handles state transitions (loading, success, error) automatically.

Quick reference


Parent	`<primer-checkout>` (in `main` slot)
Slots	`payments`, `checkout-complete`, `checkout-error`
CSS Variables	`--primer-space-small`

Examples

Default (all methods)

<primer-checkout client-token="your-token">
  <primer-main slot="main"></primer-main>
</primer-checkout>

Renders all available payment methods automatically.

Custom payment methods

<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="payments">
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
      <primer-payment-method type="PAYPAL"></primer-payment-method>
      <primer-error-message-container></primer-error-message-container>
    </div>
  </primer-main>
</primer-checkout>

Custom success screen

<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="checkout-complete">
      <h2>Thank you for your order!</h2>
      <p>Your payment has been processed.</p>
      <a href="/orders">View Orders</a>
    </div>
  </primer-main>
</primer-checkout>

Custom initialization error screen

<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="checkout-error">
      <h2>We could not load the checkout</h2>
      <p>Please try again later or contact support.</p>
    </div>
  </primer-main>
</primer-checkout>

For error details (e.g. to log or branch on the failure), listen for primer:state-change and read primerJsError from the event detail — see Error handling.

Both slots

<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="payments">
      <h2>Choose payment method</h2>
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
    </div>
    <div slot="checkout-complete">
      <h2>Order confirmed!</h2>
    </div>
  </primer-main>
</primer-checkout>

Slots

Slot	Description	Default
`payments`	Payment method area	All available methods
`checkout-complete`	Success screen	Default success component
`checkout-error`	Shown when the SDK fails to initialize (e.g. invalid client token)	Default error component

Events

<primer-main> does not emit its own events. It subscribes to parent events internally to manage slot visibility. When bypassing <primer-main>, you handle these events yourself.

Relevant parent events

Event	Emitted by	How `<primer-main>` uses it
`primer:state-change`	`<primer-checkout>`	Switches between `payments`, `checkout-complete`, and `checkout-error` slots based on `isSuccessful` and `primerJsError`
`primer:methods-update`	`<primer-checkout>`	Populates the `payments` slot with available methods (when slot is not customized)

When you bypass `<primer-main>`

If you use a custom <div slot="main"> instead of <primer-main>, you must handle these events directly:

const checkout = document.querySelector('primer-checkout');

checkout.addEventListener('primer:state-change', (event) => {
  const { isSuccessful, isProcessing } = event.detail;

  if (isSuccessful) {
    document.getElementById('payment-form').hidden = true;
    document.getElementById('success-screen').hidden = false;
  }
});

CSS properties

Property	Description	Default
`--primer-space-small`	Gap between payment methods	`8px`

States

This component automatically manages visibility based on checkout state:

State	Description	Visible Slot
Loading	SDK initializing	Loading indicator
Ready	Payment methods available	`payments` slot
Processing	Payment in progress	`payments` slot (with loading overlay)
Success	Payment completed	`checkout-complete` slot
Error	SDK initialization failed	`checkout-error` slot

Usage guidelines

Do

Use for structured customization with automatic state handling
Include <primer-error-message-container> when customizing payments slot (for payment failures)
Provide custom success screen via checkout-complete slot
Provide a custom initialization-failure screen via checkout-error slot

Don’t

Don’t use if you need full control over state — use custom main slot on <primer-checkout> instead
Don’t confuse checkout-error (SDK initialization failures) with <primer-error-message-container> (payment failures) — see Error handling

Alternative: full customization

For complete control, bypass <primer-main>:

<primer-checkout client-token="your-token">
  <div slot="main">
    <!-- Your implementation -->
    <!-- Must handle state via primer:state-change event -->
  </div>
</primer-checkout>

Content guidelines

Success screen text

Do	Don’t
”Thank you for your order!"	"Payment successful” (too technical)
“Your payment has been processed"	"Transaction complete”

Section headings

Do	Don’t
”Choose payment method"	"SELECT YOUR PAYMENT METHOD”
Use sentence case	Use all caps

primer-checkout

Parent component

Layout customization

Slot usage guide

Error handling

Error display patterns

Web

Main component

<primer-main>

Quick reference

Examples

Default (all methods)

Custom payment methods

Custom success screen

Custom initialization error screen

Both slots

Slots

Events

Relevant parent events

When you bypass `<primer-main>`

CSS properties

States

Usage guidelines

Do

Don’t

Alternative: full customization

Content guidelines

Success screen text

Section headings

See also

primer-checkout

Layout customization

Error handling

​<primer-main>

​Quick reference

​Examples

​Default (all methods)

​Custom payment methods

​Custom success screen

​Custom initialization error screen

​Both slots

​Slots

​Events

​Relevant parent events

​When you bypass <primer-main>

​CSS properties

​States

​Usage guidelines

​Do

​Don’t

​Alternative: full customization

​Content guidelines

​Success screen text

​Section headings

​See also

primer-checkout

Layout customization

Error handling

<primer-main>

Quick reference

Examples

Default (all methods)

Custom payment methods

Custom success screen

Custom initialization error screen

Both slots

Slots

Events

Relevant parent events

When you bypass `<primer-main>`

CSS properties

States

Usage guidelines

Do

Don’t

Alternative: full customization

Content guidelines

Success screen text

Section headings

See also