Spacing Tokens

Primer Checkout iOS SDK is currently in beta (v3.0.0-beta.8). The API is subject to change before the stable release.

SpacingOverrides lets you override the spacing scale the Primer iOS SDK uses for padding, gaps, and layout rhythm across the prebuilt screens and the composable views. You pass it through the spacing parameter of PrimerCheckoutTheme. Every property is optional. A nil value falls back to the internal default token, so you only set the values you want to change.

@available(iOS 15.0, *)
public struct SpacingOverrides: Equatable

Internal DesignTokens (auto-generated from JSON) remain the source of truth for spacing. SpacingOverrides merges your values on top of those defaults — any token you leave nil keeps its internal default.

Properties

All properties are CGFloat? and measured in points. The default column shows the internal token value used when you leave the property nil.

Property	Type	Default	Description
`primerSpaceXxsmall`	`CGFloat?`	2	Gap between the country name and its code line in the country picker.
`primerSpaceXsmall`	`CGFloat?`	4	Gap between an input field’s label, box and error message, and other small icon-and-text gaps, such as in the header buttons.
`primerSpaceSmall`	`CGFloat?`	8	Gaps between closely related elements, such as payment method rows, saved payment method rows, the billing address title and its fields, and the text and icons inside an input field.
`primerSpaceMedium`	`CGFloat?`	12	Space below each input field and between side-by-side fields, the inner horizontal padding of input fields, the pay button’s horizontal padding, the padding inside saved payment method rows, and the gap between the payment method list and its heading. Other screens, such as the error screen, use it for spacing too. It also sets input field height.
`primerSpaceLarge`	`CGFloat?`	16	Container padding, major gaps.
`primerSpaceXlarge`	`CGFloat?`	20	Spacing between major sections.
`primerSpaceXxlarge`	`CGFloat?`	24	Largest section spacing.

Input field height is max(44, 2 × primerSpaceMedium + bodyLarge line height). With the default 20pt body line height, primerSpaceMedium: 16 gives 52pt fields. Fields grow with Dynamic Type.

Initializer

Every parameter defaults to nil, so you can construct an override that touches only the tokens you care about.

public init(
  primerSpaceXxsmall: CGFloat? = nil,
  primerSpaceXsmall: CGFloat? = nil,
  primerSpaceSmall: CGFloat? = nil,
  primerSpaceMedium: CGFloat? = nil,
  primerSpaceLarge: CGFloat? = nil,
  primerSpaceXlarge: CGFloat? = nil,
  primerSpaceXxlarge: CGFloat? = nil
)

Overriding spacing

Build a PrimerCheckoutTheme with a SpacingOverrides value and pass it to your checkout. The example below loosens the spacing between fields, payment method rows, and sections. Because primerSpaceMedium also sets the field padding, input fields are 52pt tall.

import SwiftUI
import PrimerSDK

let theme = PrimerCheckoutTheme(
  spacing: SpacingOverrides(
    primerSpaceSmall: 12,
    primerSpaceMedium: 16,
    primerSpaceLarge: 20
  )
)

Apply the theme on the prebuilt modal by passing it to primerTheme:

struct CheckoutView: View {
  let clientToken: String

  var body: some View {
    PrimerCheckout(
      clientToken: clientToken,
      primerTheme: theme
    ) { state in
      handle(state)
    }
  }
}

When you embed the composable views inline, pass the theme to the PrimerCheckoutSession instead. The composable views resolve the merged tokens from the session.

struct InlineCheckoutView: View {
  @StateObject private var session: PrimerCheckoutSession

  init(clientToken: String) {
    _session = StateObject(
      wrappedValue: PrimerCheckoutSession(clientToken: clientToken, theme: theme)
    )
  }

  var body: some View {
    ScrollView {
      PrimerCardForm()
    }
    .primerCheckoutSession(session) { state in
      handle(state)
    }
  }
}

Spacing tokens form a scale. Overriding primerSpaceSmall, primerSpaceMedium, and primerSpaceLarge together keeps the rhythm consistent; changing a single step in isolation can make the layout feel uneven.

These tokens control the spacing used inside Primer’s own views. They do not affect the padding you add around the SDK in your own layout — use standard SwiftUI modifiers such as .padding() for that.

PrimerTheme

The theme container that carries spacing and the other override groups.

Shape Tokens

Corner-radius and border-width override tokens.

​Properties

​Initializer

​Overriding spacing

​See also

PrimerTheme

Shape Tokens

Properties

Initializer

Overriding spacing

See also