Skip to main content
Primer Checkout lets you customize the structure and layout of your checkout using a slot-based architecture. You can rearrange components, insert your own content, and control how payment methods are displayed, while Primer continues to handle payment logic, state management, and security for you.

​
Use slots to insert your own content

Primer Checkout uses slots as the primary mechanism for layout customization. Slots are named placeholders in components where you can insert your own content or Primer components.
Slots are designated areas within Web Components where custom content can be inserted. Each slot has a specific name (i.e. main) that determines where the content will appear.
<primer-checkout client-token="your-client-token">
  <div slot="main">
    <!-- This content will be inserted into the "main" slot of primer-checkout -->
    Your custom content goes here
  </div>
</primer-checkout>
When a component renders, it replaces each slot with the content you provide. If you don’t provide content for a slot, the component uses default content instead.

​
Component hierarchy and available slots

The checkout layout follows a hierarchical structure with slots at each level:
Cprimer-checkout
└── Mprimer-mainslot: main
├── PPayment Methodsslot: payments
│ ├── ◇primer-payment-method
│ ├── Fprimer-card-form
│ └── !primer-error-message-container
└── →Success Screenslot: checkout-complete
CRoot
MLayout
PContainer
FCard form
#Input fields
→Actions / errors
◇Payment method
The root component that initializes the SDK and provides the checkout context.Available Slots:
  • main - The main content area for the checkout experience
<primer-checkout client-token="your-token">
  <div slot="main">
    <!-- Your custom checkout UI -->
  </div>
</primer-checkout>
A pre-built component that manages checkout states and provides additional slots for customization.Available Slots:
  • payments - Contains payment method components
  • checkout-complete - Content shown on successful payment
<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="payments">
      <!-- Your payment methods layout -->
    </div>
    <div slot="checkout-complete">
      <!-- Your success screen -->
    </div>
  </primer-main>
</primer-checkout>
Error states are managed by the parent <primer-checkout> component, not by <primer-main>. If you need custom error handling, implement it directly in the main slot of <primer-checkout> without using <primer-main>.

​
Customization approaches

You can customize the checkout layout in two main ways:

​
Using <primer-main> with custom slots

This approach allows you to customize specific parts of the checkout while relying on <primer-main> to handle state management: 
<primer-checkout client-token="your-token">
  <primer-main slot="main">
    <div slot="payments">
      <h2>Select Payment Method</h2>
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
      <primer-payment-method type="PAYPAL"></primer-payment-method>
    </div>
  </primer-main>
</primer-checkout>
Benefits of this approach:
  • <primer-main> handles state transitions (loading, success, error)
  • You only need to provide content for the slots you want to customize
  • Default content is used for any slots you don’t provide

​
Fully custom implementation

For complete control, you can bypass <primer-main> entirely and provide your own implementation. This requires handling state management yourself through events. For details on implementing fully custom layouts, see Layout with Event Handling.

​
Why slot names matter

Slot names are crucial for several reasons:
  1. Component targeting - Names tell the component exactly where to insert your content
  2. Default content - Components can provide default content for slots that aren’t filled
  3. Preventing accidental rendering - Content without a matching slot won’t be displayed
  4. Multiple insertion points - Different named slots allow multiple insertion points
Using the wrong slot name or omitting it entirely can lead to content not appearing where expected.

​
Styling custom layouts

When styling custom layouts, use CSS variables for consistency: 
.payment-section {
  padding: var(--primer-space-medium);
  border-radius: var(--primer-radius-small);
  background-color: var(--primer-color-background-outlined-default);
}

.payment-section h2 {
  color: var(--primer-color-text-primary);
  font-family: var(--primer-typography-title-large-font);
  font-size: var(--primer-typography-title-large-size);
}
Using these properties ensures your custom layout maintains visual consistency with the checkout components. For detailed information on available components and their slots, refer to the component SDK Reference documentation:

​
Next steps

Slot Architecture Explorer

Explore the full component hierarchy and all available slots interactively

Layout with Event Handling

Learn about events, dynamic rendering, and fully custom implementations

Error Handling

Handle payment failures and display error messages

Design Tokens Explorer

Explore CSS variables and see which components they affect