Layout customization

Primer Checkout lets you customize the structure and layout of your checkout using platform-specific customization points. 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.

How layout customization works

Web
Android
iOS

Primer Checkout uses named slots within Web Components 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">
    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.

Primer Checkout SDK uses standard Jetpack Compose @Composable slot parameters for layout customization. Every component provides a Defaults object with pre-built sub-components that you can selectively override.

Component	Defaults Object	Sub-components
`PrimerCheckoutSheet`	`PrimerCheckoutSheetDefaults`	`Splash`, `Loading`, `Success`, `Error`, `PaymentMethodSelection`
`PrimerCardForm`	`CardFormDefaults`	`CardNumberField`, `ExpiryField`, `CvvField`, `CardholderField`, `SubmitButton`
`PrimerPaymentMethods`	`PaymentMethodsDefaults`	`SectionHeader`, `Method`, `EmptyState`

Primer Checkout SDK uses scope-based customization via closures. Each scope exposes properties for replacing individual fields, sections, or entire screens with custom SwiftUI views.

Scope	Customization points
`PrimerCheckoutScope`	`container`, `splashScreen`, `loadingScreen`, `errorScreen`
`PrimerPaymentMethodSelectionScope`	`screen`, `paymentMethodItem`, `categoryHeader`, `emptyStateView`
`PrimerCardFormScope`	`screen`, `cardInputSection`, `billingAddressSection`, `submitButton`, `errorScreen`, field configs
`PrimerWebRedirectScope`	`screen`, `payButton`, `submitButtonText`
`PrimerFormRedirectScope`	`screen`, `formSection`, `submitButton`, `submitButtonText`
`PrimerQRCodeScope`	`screen`

Component hierarchy and customization points

Web
Android
iOS

The checkout layout follows a hierarchical structure with slots at each level:

<primer-checkout> Component

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>

<primer-main> Component (Optional)

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

Web
Android
iOS

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.

Overriding one slot

PrimerCheckoutSheet(
    checkout = checkout,
    success = { checkoutData ->
        MyCustomSuccessScreen(checkoutData)
    },
)

Using standalone components with CheckoutHost

PrimerCheckoutHost lets you embed checkout components inline (without a modal sheet), giving you full control over layout:

PrimerCheckoutHost(checkout = checkout, onEvent = { /* ... */ }) {
    Column(modifier = Modifier.padding(16.dp)) {
        val cardFormController = rememberCardFormController(checkout)
        PrimerCardForm(controller = cardFormController)

        Spacer(modifier = Modifier.height(16.dp))

        val paymentMethodsController = rememberPaymentMethodsController(checkout)
        PrimerPaymentMethods(controller = paymentMethodsController)
    }
}

Mixing defaults with custom content

val cardFormController = rememberCardFormController(checkout)

PrimerCardForm(
    controller = cardFormController,
    cardDetails = {
        CardFormDefaults.CardDetailsContent(cardFormController)
    },
    submitButton = {
        MyBrandedPayButton(
            onClick = { cardFormController.submit() },
        )
    },
)

Modifier support

All components accept a Modifier parameter for standard Compose layout control:

PrimerCardForm(
    controller = cardFormController,
    modifier = Modifier
        .fillMaxWidth()
        .padding(16.dp),
)

Field-level customization

Override individual field labels, placeholders, and styling:

cardScope.cardNumberConfig = InputFieldConfig(
  label: "Card number",
  placeholder: "0000 0000 0000 0000"
)

cardScope.cvvConfig = InputFieldConfig(
  styling: PrimerFieldStyling(cornerRadius: 12, borderColor: .gray)
)

Section-level customization

Replace entire sections with custom SwiftUI views:

checkoutScope.splashScreen = {
  AnyView(
    VStack {
      ProgressView()
      Text("Loading payment methods...")
    }
  )
}

Screen-level customization

Replace full screens while keeping scope access for state and actions:

if let cardScope: PrimerCardFormScope = checkoutScope.getPaymentMethodScope(PrimerCardFormScope.self) {
  cardScope.screen = { scope in
    AnyView(MyCustomCardFormScreen(scope: scope))
  }
}

Why customization points matter

Web
Android
iOS

Slot names are crucial for several reasons:

Component targeting - Names tell the component exactly where to insert your content
Default content - Components can provide default content for slots that aren’t filled
Preventing accidental rendering - Content without a matching slot won’t be displayed
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.

Compose slot parameters serve the same purpose as Web slots:

Component targeting - Named lambda parameters define exactly which part of the UI you’re customizing
Default content - Defaults objects provide pre-built content for any slots you don’t override
Type safety - The compiler enforces that your custom content matches the expected slot signature

Passing content to the wrong parameter won’t compile, preventing layout mistakes at build time.

Styling custom layouts

Web
Android
iOS

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:

Use PrimerTheme design tokens to maintain visual consistency with checkout components. See Styling Customization for details.

Use PrimerCheckoutTheme design tokens to maintain visual consistency with checkout components. Use PrimerFieldStyling for per-field styling overrides. See Styling Customization for details.

Try it live in StackBlitz

See these layout patterns working in your browser:

Example	Description
Custom sectioned layout	Payment methods organized into sections (Card, Quick Checkout, Alternative Methods)
Custom form layout	Reordered card form components with custom styling and layout

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

Documentation Index

​How layout customization works

​Component hierarchy and customization points

​Customization approaches

​Using <primer-main> with custom slots

​Fully custom implementation

​Overriding one slot

​Using standalone components with CheckoutHost

​Mixing defaults with custom content

​Modifier support

​Field-level customization

​Section-level customization

​Screen-level customization

​Why customization points matter

​Styling custom layouts

​Try it live in StackBlitz

​See also

Slot architecture explorer

Layout with event handling

Error handling

Design tokens explorer

How layout customization works

Component hierarchy and customization points

Customization approaches

Using `<primer-main>` with custom slots

Fully custom implementation

Overriding one slot

Using standalone components with CheckoutHost

Mixing defaults with custom content

Modifier support

Field-level customization

Section-level customization

Screen-level customization

Why customization points matter

Styling custom layouts

Try it live in StackBlitz

See also