> ## 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.1).
  The API is subject to change before the stable release.
</Warning>

`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`](/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
```

<Info>
  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.
</Info>

## 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       | Minimal gaps, icon padding.         |
| `primerSpaceXsmall`  | `CGFloat?` | 4       | Tight spacing, chip padding.        |
| `primerSpaceSmall`   | `CGFloat?` | 8       | Gaps between form fields.           |
| `primerSpaceMedium`  | `CGFloat?` | 12      | Section internal padding.           |
| `primerSpaceLarge`   | `CGFloat?` | 16      | Container padding, major gaps.      |
| `primerSpaceXlarge`  | `CGFloat?` | 20      | Spacing between major sections.     |
| `primerSpaceXxlarge` | `CGFloat?` | 24      | Largest section spacing.            |
| `primerSpaceBase`    | `CGFloat?` | 4       | Base unit for spacing calculations. |

## 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,
  primerSpaceBase: 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 and sections while leaving everything else at the internal defaults.

```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`](/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(
    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.
</Tip>

<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.
</Note>

## See also

<CardGroup cols={2}>
  <Card title="PrimerTheme" icon="palette" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme">
    The theme container that carries spacing and the other override groups.
  </Card>

  <Card title="Shape Tokens" icon="vector-square" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens">
    Corner-radius and border-width override tokens.
  </Card>
</CardGroup>