;
};
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
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 styles.css theme={"dark"}
primer-checkout {
--primer-color-brand: #2f98ff;
--primer-color-focus: #2f98ff;
--primer-radius-medium: 8px;
--primer-typography-brand: 'Inter', sans-serif;
}
```
```html index.html theme={"dark"}
```
When passing through a component attribute, convert kebab-case CSS variables to camelCase properties:
1. Remove the leading dashes (`--`)
2. 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:
```kotlin theme={"dark"}
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:
```swift theme={"dark"}
let theme = PrimerCheckoutTheme(
colors: ColorOverrides(
primerColorBrand: .purple
),
radius: RadiusOverrides(
primerRadiusMedium: 12
)
)
PrimerCheckout(
clientToken: clientToken,
primerTheme: theme
)
```
## Using styling variables in practice
```css theme={"dark"}
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;
}
```
```javascript theme={"dark"}
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](/sdk/primer-checkout-web/styling-variables).
`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 |
```kotlin theme={"dark"}
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](/checkout/primer-checkout/build-your-ui/design-tokens-explorer) 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 |
```swift theme={"dark"}
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](/checkout/primer-checkout/build-your-ui/design-tokens-explorer) for a complete list of all available tokens.
## Theme support
Primer Checkout supports both light and dark themes.
The default option is light. To use a dark theme, pass a `primer-dark-theme` CSS class:
```html theme={"dark"}
```
You can toggle between themes using JavaScript:
```javascript theme={"dark"}
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()`.
```kotlin theme={"dark"}
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:
```swift theme={"dark"}
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](/sdk/primer-checkout-web/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
