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

# Spacing Tokens

> Spacing override tokens for padding and layout

> [!WARNING]
>
> 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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme).

Every property is optional. A `nil` value falls back to the internal default token, so you only set the values you want to change.

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

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

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

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

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

```swift theme={"dark"}
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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session) instead. The composable views resolve the merged tokens from the session.

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

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

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

## See also

> [card] [PrimerTheme](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme.md)
>
> The theme container that carries spacing and the other override groups.

> [card] [Shape Tokens](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens.md)
>
> Corner-radius and border-width override tokens.


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