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

# PrimerTheme

> Central theming configuration for all Primer Checkout components

> [!WARNING]
>
> Primer Checkout Android SDK is currently in **beta** (v3.0.0-beta.8).
> The API is subject to change before the stable release.

Root theme container holding all design token groups. Pass to `PrimerCheckoutSheet` or `PrimerCheckoutHost` via the `theme` parameter.

## Definition

```kotlin theme={"dark"}
data class PrimerTheme(
    val lightColorTokens: LightColorTokens = LightColorTokens(),
    val darkColorTokens: DarkColorTokens = DarkColorTokens(),
    val appearanceMode: PrimerAppearanceMode = PrimerAppearanceMode.SYSTEM,
    val widthTokens: WidthTokens = WidthTokens(),
    val radiusTokens: RadiusTokens = RadiusTokens(),
    val sizeTokens: SizeTokens = SizeTokens(),
    val spacingTokens: SpacingTokens = SpacingTokens(),
    val typographyTokens: TypographyTokens = TypographyTokens(),
)
```

## Properties

| Property | Type | Description |
| - | - | - |
| `lightColorTokens` | [`LightColorTokens`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/theming/color-tokens) | Color tokens for light mode |
| `darkColorTokens` | [`DarkColorTokens`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/theming/color-tokens) | Color tokens for dark mode. Extends `LightColorTokens`. |
| `appearanceMode` | `PrimerAppearanceMode` | Whether the checkout follows the system theme (`SYSTEM`, default) or is pinned to `LIGHT` or `DARK` |
| `widthTokens` | [`WidthTokens`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/theming/shape-tokens) | Border widths for inputs in their default, focus, selected, and error states |
| `radiusTokens` | [`RadiusTokens`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/theming/shape-tokens) | Corner radius for cards, inputs, bottom sheets |
| `sizeTokens` | [`SizeTokens`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/theming/shape-tokens) | Sizes for icons and touch targets |
| `spacingTokens` | [`SpacingTokens`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/theming/spacing-tokens) | Padding and margin values |
| `typographyTokens` | [`TypographyTokens`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/theming/typography-tokens) | Font sizes, weights, and line heights |

## PrimerAppearanceMode

```kotlin theme={"dark"}
enum class PrimerAppearanceMode {
    SYSTEM,
    LIGHT,
    DARK,
}
```

| Value | Description |
| - | - |
| `SYSTEM` | Follows the device's light or dark setting. Default. |
| `LIGHT` | Always uses `lightColorTokens`. |
| `DARK` | Always uses `darkColorTokens`. |

```kotlin theme={"dark"}
val theme = PrimerTheme(appearanceMode = PrimerAppearanceMode.DARK)
```

## Methods

### isDarkAppearance

```kotlin theme={"dark"}
@Composable
fun isDarkAppearance(): Boolean
```

Returns `true` when the checkout is dark right now, given `appearanceMode` and the system setting.

### colorTokens

```kotlin theme={"dark"}
@Composable
fun colorTokens(darkTheme: Boolean = isDarkAppearance()): LightColorTokens
```

Returns `darkColorTokens` when `darkTheme` is `true`, `lightColorTokens` otherwise. Defaults to the appearance resolved from `appearanceMode`.

## Material 3 Integration

`PrimerTheme` automatically maps color tokens to a Material 3 `ColorScheme`. Material components used within the checkout tree (such as `ModalBottomSheet`) inherit your Primer tokens without additional configuration.

Both `PrimerCheckoutSheet` and `PrimerCheckoutHost` wrap content in a `MaterialTheme` that applies this mapping internally.

### Color mapping

| M3 Role | Primer Token | Notes |
| - | - | - |
| `primary` | `primerColorBrand` | |
| `onPrimary` | `primerColorOnBrand` | |
| `primaryContainer` | `primerColorBlue900` | |
| `onPrimaryContainer` | `primerColorOnBrand` | |
| `inversePrimary` | `primerColorBlue500` | |
| `secondary` | `primerColorGray600` | |
| `onSecondary` | `primerColorOnBrand` | |
| `secondaryContainer` | `primerColorGray200` | |
| `onSecondaryContainer` | `primerColorTextPrimary` | |
| `tertiary` | `primerColorBlue500` | |
| `onTertiary` | `primerColorOnBrand` | |
| `tertiaryContainer` | `primerColorGray200` | |
| `onTertiaryContainer` | `primerColorTextPrimary` | |
| `background` | `primerColorBackgroundPrimary` | |
| `onBackground` | `primerColorTextPrimary` | |
| `surface` | `primerColorBackgroundPrimary` | |
| `onSurface` | `primerColorTextPrimary` | |
| `surfaceVariant` | `primerColorGray100` | |
| `onSurfaceVariant` | `primerColorTextSecondary` | |
| `surfaceTint` | `primerColorBrand` | |
| `inverseSurface` | `primerColorGray900` | |
| `inverseOnSurface` | `primerColorGray000` | |
| `surfaceBright` | `primerColorGray000` (light) / `primerColorGray300` (dark) | mode-specific |
| `surfaceDim` | `primerColorGray100` (light) / `primerColorGray000` (dark) | mode-specific |
| `surfaceContainer` | `primerColorGray100` | |
| `surfaceContainerHigh` | `primerColorGray200` | |
| `surfaceContainerHighest` | `primerColorGray300` | |
| `surfaceContainerLow` | `primerColorGray100` | |
| `surfaceContainerLowest` | `primerColorBackgroundPrimary` | |
| `error` | `primerColorRed500` | |
| `onError` | `primerColorOnBrand` | |
| `errorContainer` | `primerColorRed100` | |
| `onErrorContainer` | `primerColorTextNegative` | |
| `outline` | `primerColorBorderOutlinedDefault` | |
| `outlineVariant` | `primerColorGray300` | |
| `scrim` | `Color.Black` (alpha 0.32) | hardcoded |

Overriding a Primer token automatically updates every M3 role that references it. No separate M3 configuration is needed. The `primerColorGray*`, `primerColorRed*`, `primerColorBlue*`, and `primerColorGreen*` palette tokens are internal; override the semantic tokens instead.

## LocalPrimerTheme

```kotlin theme={"dark"}
val LocalPrimerTheme = staticCompositionLocalOf { PrimerTheme() }
```

Compose `CompositionLocal` providing the current `PrimerTheme`. Set automatically by `PrimerCheckoutSheet` and `PrimerCheckoutHost`. Access with `LocalPrimerTheme.current` inside the checkout composable tree.


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