Styles and CSS

Primer Checkout is fully customizable using CSS variables. 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

You can apply styling in two ways - directly in your CSS or through component attributes.

CSS
HTML

styles.css

/* Apply styling directly in your CSS */
primer-checkout {
  --primer-color-brand: #2f98ff;
  --primer-color-focus: #2f98ff;
  --primer-radius-medium: 8px;
  --primer-typography-brand: 'Inter', sans-serif;
}

index.html

<!-- Apply styling through component attributes -->
<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

Using Styling Variables in Practice

With CSS Variables
With customStyles property

/* Customizing all components */
primer-checkout {
  /* Brand Colors */
  --primer-color-brand: #663399;
  --primer-color-focus: #663399;
  --primer-color-loader: #663399;

  /* Text Colors */
  --primer-color-text-primary: #333333;
  --primer-color-text-secondary: rgba(51, 51, 51, 0.62);

  /* Typography */
  --primer-typography-brand: 'Helvetica Neue', sans-serif;

  /* Spacing (default: 12px) */
  --primer-space-medium: 16px;

  /* Border Radius */
  --primer-radius-medium: 8px;
}

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

// Apply to component
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.

Available Styling Variables

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

Theme Support

Primer Checkout supports both light and dark themes using CSS classes. The default option is light. To use a dark theme, pass a primer-dark-theme CSS class:

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

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.

Checkout

​Styling Methods

​Using Styling Variables in Practice

​Available Styling Variables

​Theme Support

​Try it out

Styling Methods

Using Styling Variables in Practice

Available Styling Variables

Theme Support

Try it out