> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PrimerCheckoutTheme

> Root design-token override container for the checkout UI

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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

```swift theme={"dark"}
@available(iOS 15.0, *)
public struct PrimerCheckoutTheme: Equatable
```

## Initializer

```swift theme={"dark"}
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?`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/color-tokens) | `nil` | Color token overrides applied in light mode. `nil` uses internal defaults. |
| `darkColors` | [`ColorOverrides?`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/color-tokens) | `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?`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens) | `nil` | Corner radius token overrides. `nil` uses internal defaults. |
| `spacing` | [`SpacingOverrides?`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/spacing-tokens) | `nil` | Spacing (padding and margin) token overrides. `nil` uses internal defaults. |
| `sizes` | [`SizeOverrides?`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens) | `nil` | Size token overrides for icons and touch targets. `nil` uses internal defaults. |
| `typography` | [`TypographyOverrides?`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/typography-tokens) | `nil` | Typography token overrides (font, weight, size, line height, letter spacing). `nil` uses internal defaults. |
| `width` | [`WidthOverrides?`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens) | `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](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/color-tokens.md) |
| Spacing | `SpacingOverrides` | Padding and margin scale | [Spacing tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/spacing-tokens.md) |
| Typography | `TypographyOverrides` | Brand font family, title and body text styles, and the field error style | [Typography tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/typography-tokens.md) |
| Radius | `RadiusOverrides` | Corner radius scale | [Shape tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens.md) |
| Sizes | `SizeOverrides` | Icon and touch-target sizes | [Shape tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens.md) |
| Border width | `WidthOverrides` | Border widths for the default, focus, error, and selected states | [Shape tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens.md) |

> [!NOTE]
>
> The [Shape tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens.md) 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](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout.md) |
| `PrimerCheckoutSession` (custom SwiftUI layout) | `theme` | [PrimerCheckoutSession](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session.md) |
| `PrimerCheckoutPresenter` (UIKit) | `primerTheme` | [PrimerCheckoutPresenter](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter.md) |

### With the managed view

```swift theme={"dark"}
import SwiftUI
import PrimerSDK

struct CheckoutView: View {
  let clientToken: String

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

### With a custom layout

```swift theme={"dark"}
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.

```swift theme={"dark"}
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
  )
)
```

> [!TIP]
>
> 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.

## See also

> [card] [Color tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/color-tokens.md)
>
> Override brand, background, text, border, and icon colors for light and dark mode.

> [card] [Typography tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/typography-tokens.md)
>
> Customize title and body text styles.

> [card] [Spacing tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/spacing-tokens.md)
>
> Tune padding and margin values.

> [card] [Shape tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens.md)
>
> Radius, size, and border-width overrides.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.