Skip to main content
Primer Checkout provides a set of Web Components that work together to create a complete payment experience. This page gives you an overview of all available components and how they relate to each other.

​
Component hierarchy

The components follow a hierarchical structure where parent components provide context to their children. Each parent literally contains its children. The spatial nesting mirrors the DOM nesting.

​
Core components

These are the essential components for building a checkout experience.
ComponentPurpose
<primer-checkout>Root component that initializes the SDK and provides checkout context
<primer-main>Manages checkout states and provides layout slots
<primer-payment-method>Renders a specific payment method (card, PayPal, Apple Pay, etc.)
<primer-payment-method-container>Container for filtering and organizing multiple payment methods

​
Card form components

Components for building custom card payment forms.
ComponentPurpose
<primer-card-form>Container that provides context for card inputs
<primer-input-card-number>Secure hosted input for card number
<primer-input-card-expiry>Secure hosted input for expiry date
<primer-input-cvv>Secure hosted input for CVV
<primer-input-cardholder-name>Input for cardholder name
<primer-card-form-submit>Submit button with built-in loading states
<primer-input-label>Label component for card inputs
<primer-input-wrapper>Wrapper for styling and layout of inputs
<primer-billing-address>Billing address collection form

​
Utility components

Components that help with specific use cases.
ComponentPurpose
<primer-error-message-container>Displays payment error messages
<primer-vault-manager>Manages saved payment methods
<primer-show-other-payments>Toggle button to show additional payment methods

​
Basic usage

Here’s how the core components work together: 
<primer-checkout client-token="your-client-token">
  <primer-main slot="main">
    <div slot="payments">
      <!-- Payment methods appear here -->
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
      <primer-payment-method type="PAYPAL"></primer-payment-method>

      <!-- Error display -->
      <primer-error-message-container></primer-error-message-container>
    </div>

    <div slot="checkout-complete">
      <h2>Payment successful!</h2>
    </div>
  </primer-main>
</primer-checkout>

​
How components communicate

Components communicate through:
  1. Context inheritance - Child components receive context from their parents (e.g., card inputs receive form context from <primer-card-form>)
  2. Events - Components emit events that you can listen to for state changes
  3. Slots - Named slots allow you to inject custom content at specific points
For details on events, see the Events guide.

​
Customization at each level

Each component supports customization:
  • <primer-checkout> - SDK options, theming, global configuration
  • <primer-main> - Layout structure through slots
  • <primer-payment-method> - Payment method-specific options
  • <primer-card-form> - Complete control over card form layout and styling

​
See also

Using Slots

Learn how to customize layout with slots

Build a custom card form

Step-by-step tutorial for card form customization

Styles and CSS

Customize appearance with CSS variables

SDK Reference

Detailed API documentation for all components