Primer Checkout Styling API
Primer Checkout uses styling variables (implemented as CSS Variables) to maintain a consistent design language across components. These variables provide a standardized way to customize the appearance of your checkout UI.
Styling Methods
You can apply styling in two ways:
CSS Variables Method
JSON Properties Method
/* Apply styling directly in your CSS */
primer-checkout {
--primer-color-brand: #2f98ff;
--primer-radius-medium: 8px;
--primer-typography-brand: 'Inter', sans-serif;
}
<!-- Apply styling through component attributes -->
<primer-checkout
customStyles='{"primerColorBrand":"#2f98ff","primerRadiusMedium":"8px"}'
></primer-checkout>
CSS to JSON Conversion
When using the JSON method, 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
Core Styling Variables
These variables control the fundamental aspects of your checkout UI, from colors to spacing.
| CSS Variable | Type | Description | Default Value | Affects |
|---|---|---|---|---|
--primer-color-brand | color | Controls the brand color across the checkout. | #2F98FF | Background color in primary primer-button, Focus outline in all components |
--primer-typography-brand | font family | Controls the brand font family across the checkout. | Inter | All typography styles |
--primer-color-background | color | Controls the background color across the checkout. | #FFFFFF | Default background color in all components except the primary primer-button |
--primer-color-focus | color | Controls the interactive focus color across the checkout. | var(--primer-color-brand) | Focus outline in all components |
Text Colors
| CSS Variable | Type | Description | Default Value | Affects |
|---|---|---|---|---|
--primer-color-text-primary | color | Controls the primary text color across the checkout. | #212121 | Secondary/Tertiary primer-button label text, primer-input input text, primer-input-label text |
--primer-color-text-placeholder | color | Controls the placeholder text color across the checkout. | #9E9E9E | primer-input placeholder text |
--primer-color-text-disabled | color | Controls the disabled text color across the checkout. | #BDBDBD | (In disabled state) Secondary/Tertiary primer-button label text, primer-input input text, primer-input-label text |
--primer-color-text-negative | color | Controls the negative text color across the checkout. | #B4324B | primer-input-error text in primer-input |
Border Radius
| CSS Variable | Type | Description | Default Value | Affects |
|---|---|---|---|---|
--primer-radius-small | radius | Controls the small border radius across the checkout. | 4px | primer-input-wrapper |
--primer-radius-medium | radius | Controls the medium border radius across the checkout. | 8px | Primary/Secondary primer-button |
Spacing
| CSS Variable | Type | Description | Default Value | Affects |
|---|---|---|---|---|
--primer-space-xsmall | spacing | Controls the x-small spacing across the checkout. | 4px | primer-input-wrapper (Spacing between primer-input-label & primer-input) |
--primer-space-small | spacing | Controls the small spacing across the checkout. | 8px | primer-card-form, primer-input-card-number |
--primer-space-medium | spacing | Controls the medium spacing across the checkout. | 12px | Paddings in primer-button, primer-input-wrapper, Spacings inside primer-card-form |
Typography
The following variables control text appearance across components, ensuring consistent text styling and readability.
Title Large
| CSS Variable | Type | Description | Default Value | Affects |
|---|---|---|---|---|
--primer-typography-title-large-font | font family | Controls the font family of the title-large typography style. | var(--primer-typography-brand) | Primary/Secondary/Tertiary primer-button label text |
--primer-typography-title-large-weight | font weight | Controls the font weight of the title-large typography style. | 550 | Primary/Secondary/Tertiary primer-button label text |
--primer-typography-title-large-size | font size | Controls the font size of the title-large typography style. | 16px | Primary/Secondary/Tertiary primer-button label text |
--primer-typography-title-large-line-height | line height | Controls the line height of the title-large typography style. | 20px | Primary/Secondary/Tertiary primer-button label text |
--primer-typography-title-large-letter-spacing | letter spacing | Controls the letter spacing of the title-large typography style. | -0.2px | Primary/Secondary/Tertiary primer-button label text |
Body Large
| CSS Variable | Type | Description | Default Value | Affects |
|---|---|---|---|---|
--primer-typography-body-large-font | font family | Controls the font family of the body-large typography style. | var(--primer-typography-brand) | Input/Placeholder text in primer-input |
--primer-typography-body-large-weight | font weight | Controls the font weight of the body-large typography style. | 400 | Input/Placeholder text in primer-input |
--primer-typography-body-large-size | font size | Controls the font size of the body-large typography style. | 16px | Input/Placeholder text in primer-input |
--primer-typography-body-large-line-height | line height | Controls the line height of the body-large typography style. | 20px | Input/Placeholder text in primer-input |
--primer-typography-body-large-letter-spacing | letter spacing | Controls the letter spacing of the body-large typography style. | -0.2px | Input/Placeholder text in primer-input |
Body Small
| CSS Variable | Type | Description | Default Value | Affects |
|---|---|---|---|---|
--primer-typography-body-small-font | font family | Controls the font family of the body-small typography style. | var(--primer-typography-brand) | primer-input-error, primer-input-label |
--primer-typography-body-small-weight | font weight | Controls the font weight of the body-small typography style. | 400 | primer-input-error, primer-input-label |
--primer-typography-body-small-size | font size | Controls the font size of the body-small typography style. | 12px | primer-input-error, primer-input-label |
--primer-typography-body-small-line-height | line height | Controls the line height of the body-small typography style. | 16px | primer-input-error, primer-input-label |
--primer-typography-body-small-letter-spacing | letter spacing | Controls the letter spacing of the body-small typography style. | 0 | primer-input-error, primer-input-label |
Outlined Container
These styling variables control the appearance of outlined containers like input wrappers and buttons.
Background Properties
| CSS Variable | Type | Description | Default Value | Affects |
|---|---|---|---|---|
--primer-color-background-outlined-default | color | Controls the background color of the outlined container in default state. | var(--primer-color-background) | (In default state) Background color in primer-input-wrapper, secondary primer-button |
--primer-color-background-outlined-hover | color | Controls the background color of the outlined container in hover state. | var(--primer-color-background-outlined-default) | (In hover state) Background color in primer-input-wrapper, secondary primer-button |
--primer-color-background-outlined-active | color | Controls the background color of the outlined container in active state. | var(--primer-color-background-outlined-default) | (In active state) Background color in primer-input-wrapper, secondary primer-button |
--primer-color-background-outlined-error | color | Controls the background color of the outlined container in error state. | var(--primer-color-background-outlined-default) | (In error state) Background color in primer-input-wrapper |
--primer-color-background-outlined-disabled | color | Controls the background color of the outlined container in disabled state. | #F5F5F5 | (In disabled state) Background color in primer-input-wrapper, secondary primer-button |
Border Properties
| CSS Variable | Type | Description | Default Value | Affects |
|---|---|---|---|---|
--primer-color-border-outlined-default | color | Controls the border color of the outlined container in default state. | #E0E0E0 | (In default state) Border color in primer-input-wrapper, secondary primer-button |
--primer-color-border-outlined-hover | color | Controls the border color of the outlined container in hover state. | #BDBDBD | (In hover state) Border color in primer-input-wrapper, secondary primer-button |
--primer-color-border-outlined-active | color | Controls the border color of the outlined container in active state. | #9E9E9E | (In active state) Border color in primer-input-wrapper, secondary primer-button |
--primer-color-border-outlined-focus | color | Controls the border color of the outlined container in focus state. | var(--primer-color-focus) | (In focus state) Border color in primer-input-wrapper, secondary primer-button |
--primer-color-border-outlined-error | color | Controls the border color of the outlined container in error state. | #FF7279 | (In error state) Border color in primer-input-wrapper, secondary primer-button |
--primer-color-border-outlined-disabled | color | Controls the border color of the outlined container in disabled state. | #EEEEEE | (In disabled state) Border color in primer-input-wrapper, secondary primer-button |
Using Styling Variables in Practice
CSS Variables Method
Implementation Options
You can target specific components or apply global styling to all components in your checkout experience.
/* Customizing all components */
:root {
/* Colors */
--primer-color-brand: #663399;
--primer-color-text-primary: #333333;
/* Typography */
--primer-typography-body-large-font: 'Helvetica Neue', sans-serif;
/* Spacing */
--primer-space-medium: 16px;
/* Border Radius */
--primer-radius-medium: 8px;
}
JSON Properties Method
This approach is particularly useful when working with JavaScript frameworks or when you need to apply styling variables programmatically.
// Create a styling object
const myCustomStyles = {
primerColorBrand: '#663399',
primerColorTextPrimary: '#333333',
primerTypographyBodyLargeFont: 'Helvetica Neue, sans-serif',
primerSpaceMedium: '16px',
primerRadiusMedium: '8px',
};
// Apply to component
const checkoutElement = document.querySelector('primer-checkout');
checkoutElement.setAttribute('customStyles', JSON.stringify(myCustomStyles));
The component will parse the JSON and automatically apply the styles as CSS Variables internally.
Theme Support
Primer Checkout supports both light (default) and dark themes using CSS classes:
<!-- Add the theme class to your checkout container -->
<primer-checkout client-token="your-client-token" class="primer-dark-theme">
<!-- Your checkout content -->
</primer-checkout>
You can toggle between themes using JavaScript:
// Function to toggle between themes
function toggleTheme(isDark) {
const container = document.querySelector('primer-checkout');
container.className = isDark ? 'primer-dark-theme' : 'primer-light-theme';
}
// Examples
toggleTheme(true); // Switch to dark theme
toggleTheme(false); // Switch to light theme
This approach allows you to support both light and dark themes, toggling between them as needed.