Styles - Primer

Primer Checkout is fully customizable. You can customize colors, typography, spacing, borders, and component layout (down to the smallest visual detail) without touching internal component code or breaking upgrades.

Styling methods

Web
Android
iOS

On the web, Primer Checkout uses CSS variables for theming. You can apply styling in two ways - directly in your CSS or through component attributes.

CSS
HTML

styles.css

primer-checkout {
  --primer-color-brand: #2f98ff;
  --primer-color-focus: #2f98ff;
  --primer-radius-medium: 8px;
  --primer-typography-brand: 'Inter', sans-serif;
}

index.html

<primer-checkout
  customStyles='{"primerColorBrand":"#2f98ff","primerColorFocus":"#2f98ff","primerRadiusMedium":"8px"}'
></primer-checkout>

When passing through a component attribute, convert kebab-case CSS variables to camelCase properties:

Remove the leading dashes (--)
Convert hyphens to camelCase by removing the hyphen and capitalizing the next letter

Examples:

--primer-color-brand → primerColorBrand
--primer-space-medium → primerSpaceMedium
--primer-typography-body-large-font → primerTypographyBodyLargeFont

On Android, Primer Checkout uses a token-based design system through PrimerTheme. Pass a custom PrimerTheme to your checkout component:

val theme = PrimerTheme(
    lightColorTokens = object : LightColorTokens() {
        override val primerColorBrand: Color = Color(0xFF6C5CE7)
    },
)

PrimerCheckoutSheet(
    checkout = checkout,
    theme = theme,
)

On iOS, Primer Checkout uses PrimerCheckoutTheme for theming. Pass a custom theme to your checkout view:

let theme = PrimerCheckoutTheme(
  colors: ColorOverrides(
    primerColorBrand: .purple
  ),
  radius: RadiusOverrides(
    primerRadiusMedium: 12
  )
)

PrimerCheckout(
  clientToken: clientToken,
  primerTheme: theme
)

Using styling variables in practice

Web
Android
iOS

With CSS Variables
With customStyles property

primer-checkout {
  --primer-color-brand: #663399;
  --primer-color-focus: #663399;
  --primer-color-loader: #663399;
  --primer-color-text-primary: #333333;
  --primer-color-text-secondary: rgba(51, 51, 51, 0.62);
  --primer-typography-brand: 'Helvetica Neue', sans-serif;
  --primer-space-medium: 16px;
  --primer-radius-medium: 8px;
}

const myCustomStyles = {
  primerColorBrand: '#663399',
  primerColorFocus: '#663399',
  primerColorLoader: '#663399',
  primerColorTextPrimary: '#333333',
  primerTypographyBrand: 'Helvetica Neue, sans-serif',
  primerSpaceMedium: '16px',
  primerRadiusMedium: '8px',
};

const checkoutElement = document.querySelector('primer-checkout');
checkoutElement.setAttribute('customStyles', JSON.stringify(myCustomStyles));

This approach is particularly useful when working with JavaScript frameworks or when you need to apply styling variables programmatically.The component will parse the JSON and automatically apply the styles as CSS Variables internally.

You can see all the available styling variables on the dedicated reference page.

PrimerTheme contains five token groups:

Token Group	Class	What It Controls
Light colors	`LightColorTokens`	All colors in light mode
Dark colors	`DarkColorTokens`	All colors in dark mode
Spacing	`SpacingTokens`	Padding and margins
Typography	`TypographyTokens`	Font sizes, weights, line heights
Radius	`RadiusTokens`	Corner radius for cards, inputs, sheets
Border widths	`BorderWidthTokens`	Border widths for inputs, focus rings
Sizes	`SizeTokens`	Icon sizes and touch targets

val brandTheme = PrimerTheme(
    lightColorTokens = object : LightColorTokens() {
        override val primerColorBrand: Color = Color(0xFF6C5CE7)
        override val primerColorGray100: Color = Color(0xFFF7F7F8)
    },
    darkColorTokens = object : DarkColorTokens() {
        override val primerColorBrand: Color = Color(0xFFA29BFE)
    },
    spacingTokens = SpacingTokens(
        small = 6.dp,
        medium = 10.dp,
        large = 14.dp,
    ),
    radiusTokens = RadiusTokens(
        medium = 12.dp,
        large = 20.dp,
    ),
)

PrimerCheckoutSheet(
    checkout = checkout,
    theme = brandTheme,
)

See the Design Tokens Reference for a complete list of all available tokens.

PrimerCheckoutTheme is organized into six override categories:

Category	Type	Controls
Colors	`ColorOverrides`	Brand, text, backgrounds, borders, icons
Radius	`RadiusOverrides`	Corner radius for inputs, buttons, cards
Spacing	`SpacingOverrides`	Padding and margins
Sizes	`SizeOverrides`	Component dimensions (icons, buttons, touch targets)
Typography	`TypographyOverrides`	Font family, size, weight, line height
Border width	`BorderWidthOverrides`	Stroke widths for borders

let theme = PrimerCheckoutTheme(
  colors: ColorOverrides(
    primerColorBrand: .indigo,
    primerColorTextPrimary: Color(.label),
    primerColorBackground: Color(.systemBackground),
    primerColorBorderOutlinedFocus: .indigo
  ),
  radius: RadiusOverrides(
    primerRadiusMedium: 10,
    primerRadiusLarge: 16
  ),
  spacing: SpacingOverrides(
    primerSpaceMedium: 12,
    primerSpaceLarge: 16
  ),
  typography: TypographyOverrides(
    bodyMedium: .init(font: "Inter", size: 14)
  )
)

PrimerCheckout(
  clientToken: clientToken,
  primerTheme: theme
)

See the Design Tokens Reference for a complete list of all available tokens.

Theme support

Primer Checkout supports both light and dark themes.

Web
Android
iOS

The default option is light. To use a dark theme, pass a primer-dark-theme CSS class:

<primer-checkout client-token="your-client-token" class="primer-dark-theme">
</primer-checkout>

You can toggle between themes using JavaScript:

function toggleTheme(isDark) {
  const container = document.querySelector('primer-checkout');
  container.className = isDark ? 'primer-dark-theme' : 'primer-light-theme';
}

toggleTheme(true);
toggleTheme(false);

DarkColorTokens extends LightColorTokens and overrides base color values. Semantic tokens automatically resolve to the correct values through inheritance:

Light mode:  primerColorBackground → primerColorGray000 → #FFFFFF
Dark mode:   primerColorBackground → primerColorGray000 → #171619

The SDK detects the system theme automatically via isSystemInDarkTheme().

val theme = PrimerTheme(
    lightColorTokens = object : LightColorTokens() {
        override val primerColorBrand: Color = Color(0xFFE53E3E)
        override val primerColorBackground: Color = Color(0xFFF8F8F8)
    },
    darkColorTokens = object : DarkColorTokens() {
        override val primerColorBrand: Color = Color(0xFFFF6B6B)
    },
)

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

The built-in theme automatically adapts to the system appearance (light/dark mode). Use SwiftUI adaptive colors to support both modes:

let theme = PrimerCheckoutTheme(
  colors: ColorOverrides(
    primerColorBrand: Color("BrandColor"),        // From asset catalog
    primerColorBackground: Color(.systemBackground) // Adapts automatically
  )
)

System colors like Color(.label) and Color(.systemBackground) automatically adapt to light and dark mode without additional configuration.

Try it out

Select a preset or adjust individual tokens to see how styling variables affect the checkout appearance.

This preview shows a subset of styling variables. Interactive states (hover, focus) are not displayed. See Styling Variables for a complete reference.

Try it live in StackBlitz

See styling in action with these interactive examples:

Example	Description
Theme variations	Explore light, dark and more
Custom form styling	See custom CSS styling applied to a reordered payment form layout

Checkout

​Styling methods

​Using styling variables in practice

​Theme support

​Try it out

​Try it live in StackBlitz

Styling methods

Using styling variables in practice

Theme support

Try it out

Try it live in StackBlitz