Skip to main content

​
What is a Primer Checkout component?

Primer Checkout is built from reusable UI components. Each component represents a specific part of the checkout experience—such as the payment method selector, the card form, or the pay button—and is designed to be configured, styled, and combined without rewriting payment logic. You don’t build a checkout from scratch. You assemble and customize trusted building blocks.

​
What this means for you

Using Primer Checkout components allows you to:
  • Integrate a full checkout UI without managing sensitive payment inputs
  • Customize layout and appearance without breaking functionality
  • Keep a predictable and stable integration over time
  • Upgrade components without refactoring your application
This model lets you move fast while keeping control.

​
Under the hood

Primer Checkout components are built using Web Components, a browser standard for creating reusable and encapsulated UI elements. The SDK handles Web Component internals for you. The basics below will help you customize the checkout effectively—and you can dig deeper if you need to.

​
Why Web Components?

  • Framework-agnostic: Works with React, Vue, vanilla JS, or no framework
  • Consistent behavior: Same checkout logic everywhere
  • Future-proof: Based on native web standards, not a framework abstraction

​
Styling model: isolation by default

Each Primer component uses Shadow DOM, which means its internal HTML and CSS are isolated from your application. This prevents:
  • Your CSS from accidentally breaking checkout components
  • Component styles from leaking into your app

​
Important rule

You cannot style internal component elements with CSS selectors. Instead, Primer exposes CSS variables as the official customization API.

​
Customizing styles with CSS variables

CSS variables can cross Shadow DOM boundaries and are used to control colors, spacing, typography, and more. 
:root {
  --primer-color-brand: #6c5ce7;
  --primer-radius-small: 6px;
}
This approach allows:
  • Safe customization
  • Consistent theming
  • Runtime updates without rebuilding components

​
Content and layout with slots

Components expose slots, which are predefined areas where you can insert your own content. Think of slots as named placeholders inside a component.

​
Example

<primer-button>
  <span>Pay now</span>
</primer-button>
Slots allow you to:
  • Inject custom text or elements
  • Control layout without touching internal markup
  • Work naturally with any framework

​
Communication: events

Primer Checkout uses an event-driven architecture to communicate with your application. Instead of polling for state or calling methods directly, you listen for events that the SDK dispatches.
Primer Checkout
events→
←listens
Your Application

​
Why events?

  • Decoupled: Your code doesn’t need to know about SDK internals
  • Framework-agnostic: Standard DOM events work everywhere
  • Flexible: Listen at component level or document level
  • Predictable: Clear lifecycle events for initialization, state changes, and payment results

​
Key events

EventWhen it fires
primer:readySDK is initialized and ready
primer:state-changeCheckout state changes (loading, processing, success, error)
primer:payment-successPayment completed successfully
primer:payment-failurePayment failed
For practical implementation patterns, see the Events Guide. For a complete event reference, see Events & Callbacks Reference.

​
What the SDK handles

Primer Checkout handles this for you:
  • Browser compatibility (Chrome, Firefox, Safari, Edge)
  • Performance optimizations
  • Framework differences
  • Payment-related security concerns
You focus on integration and UX, not infrastructure.

​
Key takeaways

  • Primer Checkout is built from reusable, isolated components
  • Customization happens through configuration, slots, and CSS variables
  • The technology is designed to be stable, safe, and framework-independent
The SDK abstracts the underlying tech. The sections above cover what you need to integrate and customize effectively.

​
Next steps

Styling

Customize colors, fonts, and spacing

Layout

Control component arrangement with slots

Events

Handle payment lifecycle events

Components

Explore all available components