Components - Primer

Primer Checkout provides a set of 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

Web
Android
iOS

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.

Without vault
With vault

The iOS SDK uses a scope-based hierarchy where PrimerCheckout provides a PrimerCheckoutScope, which gives access to payment method-specific scopes.

Core Components

Web
Android
iOS

Component	Purpose
`<primer-checkout>`	Root component that initializes the SDK and provides checkout context
`<primer-main>`	Manages checkout states and provides layout customization
`<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

Checkout controllers

Function	Returns	Purpose
`rememberPrimerCheckoutController()`	`PrimerCheckoutController`	Main session controller
`rememberCardFormController()`	`PrimerCardFormController`	Card form state and actions
`rememberPaymentMethodsController()`	`PrimerPaymentMethodsController`	Available payment methods
`rememberVaultedPaymentMethodsController()`	`PrimerVaultedPaymentMethodsController`	Saved payment methods

Presentation components

Component	Description	API Reference
`PrimerCheckoutSheet`	Modal bottom sheet checkout	Reference
`PrimerCheckoutHost`	Inline checkout host	Reference
`PrimerCardForm`	Card payment form	Reference
`PrimerPaymentMethods`	Payment method list	Reference

Entry points

Component	Description	API Reference
`PrimerCheckout`	Root SwiftUI view for checkout	Reference
`PrimerCheckoutPresenter`	UIKit presenter (modal sheet)	Reference

Scopes

Scope	Purpose	API Reference
`PrimerCheckoutScope`	Top-level checkout management	Reference
`PrimerPaymentMethodSelectionScope`	Payment method list and selection	Reference
`PrimerCardFormScope`	Card form fields and validation	Reference
`PrimerApplePayScope`	Apple Pay flow	Reference
`PrimerPayPalScope`	PayPal flow	Reference
`PrimerKlarnaScope`	Klarna multi-step flow	Reference
`PrimerAchScope`	ACH multi-step flow	Reference
`PrimerWebRedirectScope`	Web redirect flow (e.g., Twint)	Reference
`PrimerFormRedirectScope`	Form-based redirect flow (e.g., BLIK, MBWay)	Reference
`PrimerQRCodeScope`	QR code flow (e.g., PromptPay)	Reference

Card Form Components

Web
Android
iOS

Component	Purpose
`<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

Defaults objects

Object	Parent Component	Sub-components
`PrimerCheckoutSheetDefaults`	`PrimerCheckoutSheet`	`Splash`, `Loading`, `Success`, `Error`, `PaymentMethodSelection`, `VaultedMethods`, `PaymentMethods`
`CardFormDefaults`	`PrimerCardForm`	`CardNumberField`, `ExpiryField`, `CvvField`, `CardholderField`, `CardNetworkField`, `CountryCodeField`, billing fields, `SubmitButton`
`PaymentMethodsDefaults`	`PrimerPaymentMethods`	`SectionHeader`, `Method`, `EmptyState`

State types

Type	Purpose	Values
`PrimerCheckoutState`	Checkout lifecycle	`Loading`, `Ready`
`PrimerCheckoutEvent`	Payment outcomes	`Success`, `Failure`
`PrimerCardFormController.State`	Card form state	Field values, validation, loading

SDK-managed fields

PrimerCardFormScope provides ViewBuilder methods that return SDK-managed card fields:

Method	Purpose
`PrimerCardNumberField`	Secure card number input with network detection
`PrimerExpiryDateField`	Expiry date input
`PrimerCvvField`	CVV/CVC input
`PrimerCardholderNameField`	Cardholder name input
`PrimerPostalCodeField`	Postal/ZIP code input
`PrimerCountryField`	Country selector
`DefaultCardFormView`	Complete default card form layout

State types

Type	Purpose	Key properties
`PrimerCheckoutState`	Checkout lifecycle	`.initializing`, `.ready`, `.success`, `.failure`, `.dismissed`
`PrimerCardFormState`	Card form state	`isValid`, `isLoading`, `fieldErrors`, `selectedNetwork`
`PrimerPaymentMethodSelectionState`	Payment method list	Available payment methods

Field configuration

Each card form field can be configured via InputFieldConfig:

cardScope.cardNumberConfig = InputFieldConfig(
  label: "Card Number",
  placeholder: "1234 5678 9012 3456",
  styling: PrimerFieldStyling(cornerRadius: 8)
)

Utility Components

Web
Android
iOS

Component	Purpose
`<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

Theming

Class	Purpose
`PrimerTheme`	Root theme container
`LightColorTokens`	Light mode colors
`DarkColorTokens`	Dark mode colors
`SpacingTokens`	Spacing values
`TypographyTokens`	Font styles
`RadiusTokens`	Corner radius
`BorderWidthTokens`	Border widths
`SizeTokens`	Component sizes

Theming

Struct	Purpose
`PrimerCheckoutTheme`	Root theme container
`ColorOverrides`	Brand, text, border, and icon colors
`RadiusOverrides`	Corner radius values
`SpacingOverrides`	Spacing values
`SizeOverrides`	Component sizes
`TypographyOverrides`	Font styles and sizes
`BorderWidthOverrides`	Border widths

Type aliases

Alias	Signature	Used for
`Component`	`() -> any View`	`splashScreen`, `loadingScreen`, `submitButton`
`ContainerComponent`	`(@escaping () -> any View) -> any View`	`container`
`ErrorComponent`	`(String) -> any View`	`errorScreen`
`PaymentMethodItemComponent`	`(CheckoutPaymentMethod) -> any View`	`paymentMethodItem`
`CardFormScreenComponent`	`(any PrimerCardFormScope) -> any View`	Card form `screen`

Basic Usage

Web
Android
iOS

<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>

@Composable
fun CheckoutScreen(clientToken: String) {
    val checkout = rememberPrimerCheckoutController(clientToken)

    PrimerCheckoutSheet(
        checkout = checkout,
        onEvent = { event ->
            when (event) {
                is PrimerCheckoutEvent.Success -> navigateToConfirmation(event.checkoutData)
                is PrimerCheckoutEvent.Failure -> {
                    Log.e("Checkout", "Failed: ${event.error.description}")
                }
            }
        },
        onDismiss = { navigateBack() },
    )
}

struct CheckoutView: View {
  let clientToken: String

  var body: some View {
    PrimerCheckout(
      clientToken: clientToken,
      primerSettings: PrimerSettings(paymentHandling: .auto),
      primerTheme: PrimerCheckoutTheme(
        colors: ColorOverrides(primerColorBrand: .blue)
      ),
      onCompletion: { state in
        switch state {
        case .success(let result):
          print("Payment: \(result.payment?.id ?? "")")
        case .failure(let error):
          print("Failed: \(error.errorId)")
        case .dismissed:
          print("Dismissed")
        default:
          break
        }
      }
    )
  }
}

How Components Communicate

Components communicate through:

Context inheritance - Child components receive context from their parents (e.g., card inputs receive form context from their parent card form)
Events - Components emit events that you can listen to for state changes
Customization points (Slots on Web, Composable lambdas on Android, Scope closures on iOS) - Allow you to inject custom content at specific points

For details on events, see the Events guide.

Customization at Each Level

Web
Android
iOS

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

PrimerCheckoutSheet / PrimerCheckoutHost - Presentation mode and event handling
PrimerCheckoutSheetDefaults - Override default screens (splash, loading, success, error)
CardFormDefaults - Customize individual card form fields
PrimerTheme - Colors, typography, spacing, and border radius

PrimerCheckout - Client token, settings, theme, and completion handling
PrimerCheckoutScope - Splash, loading, error screens, and container customization
PrimerPaymentMethodSelectionScope - Payment method list item and screen customization
PrimerCardFormScope - Card form fields, layout sections, and submit button
PrimerCheckoutTheme - Colors, typography, spacing, radius, and border widths

Using Slots

Learn how to customize layout with slots

Build a custom card form

Step-by-step tutorial for card form customization

Styles

Customize appearance with CSS variables

SDK Reference

Detailed API documentation for all components

Checkout

​Component Hierarchy

​Core Components

​Checkout controllers

​Presentation components

​Entry points

​Scopes

​Card Form Components

​Defaults objects

​State types

​SDK-managed fields

​State types

​Field configuration

​Utility Components

​Theming

​Theming

​Type aliases

​Basic Usage

​How Components Communicate

​Customization at Each Level

​See also

Using Slots

Build a custom card form

Styles

SDK Reference

Component Hierarchy

Core Components

Checkout controllers

Presentation components

Entry points

Scopes

Card Form Components

Defaults objects

State types

SDK-managed fields

State types

Field configuration

Utility Components

Theming

Theming

Type aliases

Basic Usage

How Components Communicate

Customization at Each Level

See also