PrimerTheme - Primer

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

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`	Color tokens for light mode
`darkColorTokens`	`DarkColorTokens`	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`	Border widths for inputs in their default, focus, selected, and error states
`radiusTokens`	`RadiusTokens`	Corner radius for cards, inputs, bottom sheets
`sizeTokens`	`SizeTokens`	Sizes for icons and touch targets
`spacingTokens`	`SpacingTokens`	Padding and margin values
`typographyTokens`	`TypographyTokens`	Font sizes, weights, and line heights

PrimerAppearanceMode

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

val theme = PrimerTheme(appearanceMode = PrimerAppearanceMode.DARK)

Methods

isDarkAppearance

@Composable
fun isDarkAppearance(): Boolean

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

colorTokens

@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

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.

​Definition

​Properties

​PrimerAppearanceMode

​Methods

​isDarkAppearance

​colorTokens

​Material 3 Integration

​Color mapping

​LocalPrimerTheme

Definition

Properties

PrimerAppearanceMode

Methods

isDarkAppearance

colorTokens

Material 3 Integration

Color mapping

LocalPrimerTheme