Jul 8

CSS variables support

Category: Product
Published: Jul 8

Clerk's appearance system now supports CSS variables for seamless design system integration and dynamic theming

Clerk's appearance variables object now supports CSS custom properties (CSS variables), making it easier to integrate with your existing design system and enable dynamic theming without JavaScript configuration changes.

How to use CSS variables

You can now use CSS variables directly in your appearance configuration:

styles/globals.css

:root {
  --brand-primary: oklch(49.1% 0.27 292.581);
}

@media (prefers-color-scheme: dark) {
  :root {
    --brand-primary: oklch(54.1% 0.281 293.009);
  }
}

Reference these variables in your Clerk configuration:

app/layout.tsx

<ClerkProvider
  appearance={{
    variables: {
      colorPrimary: 'var(--brand-primary)',
    },
  }}
>
  ...
</ClerkProvider>

Dynamic Theming

With CSS variables, your theme changes automatically based on user preferences, system settings, or any other CSS-driven logic:

/* Theme automatically updates based on user preference */
@media (prefers-color-scheme: dark) {
  :root {
    --brand-primary: oklch(54.1% 0.281 293.009);
  }
}

/* Or with data attributes */
[data-theme='corporate'] {
  --brand-primary: #1e40af;
}

[data-theme='creative'] {
  --brand-primary: #7c3aed;
}

No need to swap Clerk themes or update JavaScript configuration - the components automatically pick up the new colors.

Design System Integration

This enhancement makes it seamless to integrate Clerk with existing design systems:

<ClerkProvider
  appearance={{
    variables: {
      colorPrimary: 'var(--ds-color-brand-primary)',
      colorSuccess: 'var(--ds-color-semantic-success)',
      colorDanger: 'var(--ds-color-semantic-error)',
      colorNeutral: 'var(--ds-color-neutral-base)',
    },
  }}
>
  ...
</ClerkProvider>

Note

Clerk's support for CSS variables relies on color-mix() and relative color syntax, which require a modern browser (Chrome 119+, Safari 16.4+, and Firefox 128+). If your application needs to support older browsers, continue using static color values (like #ff0000 or hsl(0, 100%, 50%)) instead of CSS variables, which will use our existing JavaScript-based color manipulation.

To learn more about support for CSS variables, check out the documentation.