PrimerCheckoutTheme

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

PrimerCheckoutTheme is the single container for design-token overrides. Pass it to the entry-point APIs to restyle the checkout UI without replacing Primer’s internal token system. Internally, the SDK ships auto-generated DesignTokens that remain the source of truth, with a light and a dark set of defaults. When you supply a PrimerCheckoutTheme, the SDK merges your overrides on top of those defaults, and any nil value falls back to the internal default. Colors are the exception: colors applies in light mode only, and dark mode reads darkColors alone. A color you leave out of darkColors uses Primer’s dark default, not the matching colors value. To change a color in both modes, set it in both groups. radius, spacing, sizes, typography, and width apply in both modes. You only set the tokens you want to change.

Every override property is optional. A PrimerCheckoutTheme() with no arguments applies the SDK’s default appearance, so you can start from the defaults and override one group, or one token, at a time.

Declaration

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

Initializer

public init(
  colors: ColorOverrides? = nil,
  darkColors: ColorOverrides? = nil,
  radius: RadiusOverrides? = nil,
  spacing: SpacingOverrides? = nil,
  sizes: SizeOverrides? = nil,
  typography: TypographyOverrides? = nil,
  width: WidthOverrides? = nil
)

Parameters

Parameter	Type	Default	Description
`colors`	`ColorOverrides?`	`nil`	Color token overrides applied in light mode. `nil` uses internal defaults.
`darkColors`	`ColorOverrides?`	`nil`	Color token overrides applied in dark mode only. Any color left `nil` here uses Primer’s dark default, not the matching `colors` value.
`radius`	`RadiusOverrides?`	`nil`	Corner radius token overrides. `nil` uses internal defaults.
`spacing`	`SpacingOverrides?`	`nil`	Spacing (padding and margin) token overrides. `nil` uses internal defaults.
`sizes`	`SizeOverrides?`	`nil`	Size token overrides for icons and touch targets. `nil` uses internal defaults.
`typography`	`TypographyOverrides?`	`nil`	Typography token overrides (font, weight, size, line height, letter spacing). `nil` uses internal defaults.
`width`	`WidthOverrides?`	`nil`	Border width token overrides for the default, focus, error, and selected states. `nil` uses internal defaults.

A NaN or infinite radius, spacing, size, width, or typography number is ignored with a warning, and that token keeps its default.

Properties

PrimerCheckoutTheme is Equatable and exposes one immutable property per initializer parameter. Each is the optional value you passed to the initializer.

Property	Type	Description
`colors`	`ColorOverrides?`	The light-mode color token overrides, or `nil` for defaults.
`darkColors`	`ColorOverrides?`	The dark-mode color token overrides, or `nil` for Primer’s dark defaults.
`radius`	`RadiusOverrides?`	The radius token overrides, or `nil` for defaults.
`spacing`	`SpacingOverrides?`	The spacing token overrides, or `nil` for defaults.
`sizes`	`SizeOverrides?`	The size token overrides, or `nil` for defaults.
`typography`	`TypographyOverrides?`	The typography token overrides, or `nil` for defaults.
`width`	`WidthOverrides?`	The border width token overrides, or `nil` for defaults.

Token groups

A theme is made up of six override groups. ColorOverrides is used twice, for colors (light mode) and darkColors (dark mode). Each group is its own optional struct whose properties are all optional, so you only specify the tokens you want to change. The four documentation pages below cover the full property list, types, and defaults for every group.

Group	Override type	Covers	Reference
Colors	`ColorOverrides` (`colors`, `darkColors`)	Brand, on-brand, background, text, border, icon, focus, and loader colors	Color tokens
Spacing	`SpacingOverrides`	Padding and margin scale	Spacing tokens
Typography	`TypographyOverrides`	Brand font family, title and body text styles, and the field error style	Typography tokens
Radius	`RadiusOverrides`	Corner radius scale	Shape tokens
Sizes	`SizeOverrides`	Icon and touch-target sizes	Shape tokens
Border width	`WidthOverrides`	Border widths for the default, focus, error, and selected states	Shape tokens

The Shape tokens page documents three groups together: RadiusOverrides, SizeOverrides, and WidthOverrides.

Applying a theme

PrimerCheckoutTheme is accepted by all three entry points. The managed view and the UIKit presenter take it as primerTheme; the session takes it as theme. The .primerCheckoutSession(_:theme:onCompletion:) modifier also takes an optional theme. When you pass one, it replaces the session’s theme and applies again each time the value changes, so you can switch appearance at runtime.

Entry point	Parameter	Reference
`PrimerCheckout` (SwiftUI managed view)	`primerTheme`	PrimerCheckout
`PrimerCheckoutSession` (custom SwiftUI layout)	`theme`	PrimerCheckoutSession
`PrimerCheckoutPresenter` (UIKit)	`primerTheme`	PrimerCheckoutPresenter

With the managed view

import SwiftUI
import PrimerSDK

struct CheckoutView: View {
  let clientToken: String

  var body: some View {
    PrimerCheckout(
      clientToken: clientToken,
      primerTheme: brandTheme
    )
  }
}

With a custom layout

import SwiftUI
import PrimerSDK

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

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

  var body: some View {
    ScrollView {
      PrimerPaymentMethods()
      PrimerCardForm()
    }
    .primerCheckoutSession(session) { state in
      // React to the terminal state.
    }
  }
}

Theme example

Build a theme by composing the override groups. Each group only sets the tokens you care about; everything else inherits the SDK defaults.

import SwiftUI
import PrimerSDK

let brandTheme = PrimerCheckoutTheme(
  colors: ColorOverrides(
    primerColorBrand: Color(red: 0.91, green: 0.51, blue: 0.47),
    primerColorBackgroundPrimary: .white,
    primerColorTextPrimary: Color(white: 0.1)
  ),
  darkColors: ColorOverrides(
    primerColorBrand: Color(red: 0.95, green: 0.62, blue: 0.58)
  ),
  radius: RadiusOverrides(
    primerRadiusMedium: 12,
    primerRadiusLarge: 16
  ),
  spacing: SpacingOverrides(
    primerSpaceMedium: 16,
    primerSpaceLarge: 20
  ),
  typography: TypographyOverrides(
    titleLarge: TypographyOverrides.TypographyStyle(
      font: "Inter",
      weight: .semibold,
      size: 18,
      lineHeight: 24
    ),
    bodyMedium: TypographyOverrides.TypographyStyle(
      font: "Inter",
      weight: .regular,
      size: 14,
      lineHeight: 20
    )
  ),
  width: WidthOverrides(
    primerWidthDefault: 1,
    primerWidthFocus: 2
  )
)

Start small. Override primerColorBrand alone and Primer’s default tokens fill in the rest of the palette. Focus borders, spinners, and selected borders follow your brand color unless you set them. If your app supports dark mode, set primerColorBrand in darkColors too. Then add more tokens as your branding requires.

Color tokens

Override brand, background, text, border, and icon colors for light and dark mode.

Typography tokens

Customize title and body text styles.

Spacing tokens

Tune padding and margin values.

Shape tokens

Radius, size, and border-width overrides.

​Declaration

​Initializer

​Parameters

​Properties

​Token groups

​Applying a theme

​With the managed view

​With a custom layout

​Theme example

​See also

Color tokens

Typography tokens

Spacing tokens

Shape tokens

Declaration

Initializer

Parameters

Properties

Token groups

Applying a theme

With the managed view

With a custom layout

Theme example

See also