`Variables` prop

Properties
Usage

The variables property is used to adjust the general styles of the component's base theme, like colors, backgrounds, and typography.

It is passed as a parameter to the appearance prop, which is available wherever you initialize the Clerk integration. For most SDKs, this is done via the <ClerkProvider> component. For other SDKs, it's configured through the SDK's Clerk integration or plugin.

Properties

Name
colorPrimary
Type
string
Description
The primary color used throughout the components.
CSS variable: --clerk-color-primary
Name
colorDanger
Type
string
Description
The color used for error states.
CSS variable: --clerk-color-danger
Name
colorSuccess
Type
string
Description
The color used for success states.
CSS variable: --clerk-color-success
Name
colorWarning
Type
string
Description
The color used for warning states.
CSS variable: --clerk-color-warning
Name
colorNeutral
Type
string
Description
The color that will be used for all to generate the neutral shades the components use. This option applies to borders, backgrounds for hovered elements, hovered dropdown options.
CSS variable: --clerk-color-neutral
Name
colorForeground
Type
string
Description
The color used for text.
CSS variable: --clerk-color-foreground
Name
colorPrimaryForeground
Type
string
Description
The color used for text on the primary background.
CSS variable: --clerk-color-primary-foreground
Name
colorMutedForeground
Type
string
Description
The color used for secondary text.
CSS variable: --clerk-color-muted-foreground
Name
colorMuted
Type
string
Description
The color used for muted backgrounds.
CSS variable: --clerk-color-muted
Name
colorBackground
Type
string
Description
The background color for the card container.
CSS variable: --clerk-color-background
Name
colorInputForeground
Type
string
Description
The color used for text in input fields.
CSS variable: --clerk-color-input-foreground
Name
colorInput
Type
string
Description
The background color used for input fields.
CSS variable: --clerk-color-input
Name
colorShimmer
Type
string
Description
The color of the avatar shimmer.
CSS variable: --clerk-color-shimmer
Name
colorRing
Type
string
Description
The color of the ring when an interactive element is focused.
CSS variable: --clerk-color-ring
Name
colorShadow
Type
string
Description
The base shadow color used in the components.
CSS variable: --clerk-color-shadow
Name
colorBorder
Type
string
Description
The base border color used in the components.
CSS variable: --clerk-color-border
Name
colorModalBackdrop
Type
string
Description
The background color of the modal backdrop.
CSS variable: --clerk-color-modal-backdrop
Name
fontFamily
Type
string
Description
The font family used throughout the components. By default, it is set to inherit.
CSS variable: --clerk-font-family
Name
fontFamilyButtons
Type
string
Description
The font family used for buttons. By default, it is set to inherit.
CSS variable: --clerk-font-family-buttons
Name
fontSize
Type
string | {xs: string, sm: string, md: string, lg: string, xl: string}
Description
The font size used throughout the components. By default, this is set to 0.8125rem.
CSS variable: --clerk-font-size
Name
fontWeight
Type
{normal: number, medium: number, semibold: number, bold: number}
Description
The font weight used throughout the components. By default, this is set to {normal: 400, medium: 500, semibold: 600, bold: 700}.
CSS variable: --clerk-font-weight
Name
borderRadius
Type
string
Description
The border radius used throughout the components. By default, this is set to 0.375rem.
CSS variable: --clerk-border-radius
Name
spacing
Type
string
Description
The spacing unit used throughout the components. By default, this is set to 1rem.
CSS variable: --clerk-spacing

Deprecated properties

The following properties are deprecated as of 2025-07-15 and will be removed in the next major version of Clerk.

colorText (use colorForeground instead)
colorTextOnPrimaryBackground (use colorPrimaryForeground instead)
colorTextSecondary (use colorMutedForeground instead)
spacingUnit (use spacing instead)
colorInputText (use colorInputForeground instead)
colorInputBackground (use colorInput instead)

Usage

You can customize Clerk components by passing an object of variables to the variables property of the appearance prop.

Note

Browser Compatibility Considerations

Clerk's theming system uses modern CSS features like color-mix() and relative color syntax to automatically generate color variations from your base colors. These features require:

color-mix(): Chrome 111+, Firefox 113+, Safari 16.2+
Relative color syntax: Chrome 119+, Firefox 120+, Safari 16.4+

For broader browser support, when using the variables prop, use direct color values (e.g. colorPrimary: '#6c47ff') instead of CSS variables or modern color functions.

Apply `variables` to all Clerk components

To customize all Clerk components, pass the variables property to the appearance prop, which is available wherever you initialize the Clerk integration. For most SDKs, this is done via the <ClerkProvider> component. For other SDKs, it's configured through the SDK's Clerk integration or plugin.

In the following example, the primary color is set to blue and the text color is set to black. Since these styles are applied to the SDK's Clerk integration, which wraps the entire application, they will be applied to all Clerk components that use the primary or text color.

For React-based SDKs, pass the variables property to the appearance prop of the <ClerkProvider> component.

<ClerkProvider
  appearance={{
    variables: {
      colorPrimary: '#0000ff', // blue
      colorForeground: '#000000', // black
    },
  }}
>
  {/* ... */}
</ClerkProvider>

In Astro, pass the variables property to the appearance prop of the clerk() integration.

astro.config.mjs

import clerk from '@clerk/astro'

export default defineConfig({
  integrations: [
    clerk({
      appearance: {
        variables: {
          colorPrimary: '#0000ff', // blue
          colorForeground: '#000000', // black
        },
      },
    }),
  ],
})

In JavaScript, pass the variables property to the appearance prop of the clerk.load() method.

Use the following tabs to view the code necessary for each file.

main.js

index.html

main.js

import { Clerk } from '@clerk/clerk-js'

const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(clerkPubKey)
await clerk.load({
  appearance: {
    variables: {
      colorPrimary: '#0000ff', // blue
      colorForeground: '#000000', // black
    },
  },
})

if (clerk.isSignedIn) {
  document.getElementById('app').innerHTML = `
      <div id="user-button"></div>
    `

  const userButtonDiv = document.getElementById('user-button')

  clerk.mountUserButton(userButtonDiv)
} else {
  document.getElementById('app').innerHTML = `
      <div id="sign-in"></div>
    `

  const signInDiv = document.getElementById('sign-in')

  clerk.mountSignIn(signInDiv)
}

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Clerk + JavaScript App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="main.js" async crossorigin="anonymous"></script>
  </body>
</html>

In Vue, pass the variables property to the appearance prop of the clerkPlugin() integration.

src/main.ts

import { createApp } from 'vue'
import App from './App.vue'
import { clerkPlugin } from '@clerk/vue'

const app = createApp(App)
app.use(clerkPlugin, {
  appearance: {
    variables: {
      colorPrimary: '#0000ff', // blue
      colorForeground: '#000000', // black
    },
  },
})
app.mount('#app')

In Nuxt, pass the variables property to the appearance prop of the defineNuxtConfig() integration.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@clerk/nuxt'],
  clerk: {
    appearance: {
      variables: {
        colorPrimary: '#0000ff', // blue
        colorForeground: '#000000', // black
      },
    },
  },
})

In Fastify, pass the variables property to the appearance prop of the clerkPlugin() integration.

src/main.ts

import Fastify from 'fastify'
import { clerkPlugin } from '@clerk/fastify'

const fastify = Fastify({ logger: true })

fastify.register(clerkPlugin, {
  appearance: {
    variables: {
      colorPrimary: '#0000ff', // blue
      colorForeground: '#000000', // black
    },
  },
})

Apply `variables` to all instances of a Clerk component

You can customize all instances of a Clerk component by passing the component to the appearance prop, which is available wherever you initialize the Clerk integration. For most SDKs, this is done via the <ClerkProvider> component. For other SDKs, it's configured through the SDK's Clerk integration or plugin. The appearance prop accepts the name of the Clerk component you want to style as a key.

In the following example, the primary color is set to blue and the text color is set to black for all instances of the <SignIn /> component.

For React-based SDKs, pass the component to the appearance prop of the <ClerkProvider> component.

<ClerkProvider
  appearance={{
    signIn: {
      variables: {
        colorPrimary: '#0000ff', // blue
        colorForeground: '#000000', // black
      },
    },
  }}
>
  {/* ... */}
</ClerkProvider>

In Astro, pass the component to the appearance prop of the clerk() integration.

astro.config.mjs

import clerk from '@clerk/astro'

export default defineConfig({
  integrations: [
    clerk({
      appearance: {
        signIn: {
          variables: {
            colorPrimary: '#0000ff', // blue
            colorForeground: '#000000', // black
          },
        },
      },
    }),
  ],
})

In JavaScript, pass the component to the appearance prop of the clerk.load() method.

Use the following tabs to view the code necessary for each file.

main.js

index.html

main.js

import { Clerk } from '@clerk/clerk-js'

const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(clerkPubKey)
await clerk.load({
  appearance: {
    signIn: {
      variables: {
        colorPrimary: '#0000ff', // blue
        colorForeground: '#000000', // black
      },
    },
  },
})

if (clerk.isSignedIn) {
  document.getElementById('app').innerHTML = `
      <div id="user-button"></div>
    `

  const userButtonDiv = document.getElementById('user-button')

  clerk.mountUserButton(userButtonDiv)
} else {
  document.getElementById('app').innerHTML = `
      <div id="sign-in"></div>
    `

  const signInDiv = document.getElementById('sign-in')

  clerk.mountSignIn(signInDiv)
}

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Clerk + JavaScript App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="main.js" async crossorigin="anonymous"></script>
  </body>
</html>

In Vue, pass the component to the appearance prop of the clerkPlugin() integration.

src/main.ts

import { createApp } from 'vue'
import App from './App.vue'
import { clerkPlugin } from '@clerk/vue'

const app = createApp(App)
app.use(clerkPlugin, {
  appearance: {
    signIn: {
      variables: {
        colorPrimary: '#0000ff', // blue
        colorForeground: '#000000', // black
      },
    },
  },
})
app.mount('#app')

In Nuxt, pass the component to the appearance prop of the defineNuxtConfig() integration.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@clerk/nuxt'],
  clerk: {
    appearance: {
      signIn: {
        variables: {
          colorPrimary: '#0000ff', // blue
          colorForeground: '#000000', // black
        },
      },
    },
  },
})

In Fastify, pass the component to the appearance prop of the clerkPlugin() integration.

src/main.ts

import Fastify from 'fastify'
import { clerkPlugin } from '@clerk/fastify'

const fastify = Fastify({ logger: true })

fastify.register(clerkPlugin, {
  appearance: {
    signIn: {
      variables: {
        colorPrimary: '#0000ff', // blue
        colorForeground: '#000000', // black
      },
    },
  },
})

Apply `variables` to a single Clerk component

To customize a single Clerk component, pass the variables property to the appearance prop of the Clerk component.

The following example shows how to customize the <SignIn /> component by setting the primary color to blue and the text color to black.

Next.js

Astro

Vue

Nuxt

The following example is written for Next.js App Router but can be adapted for any React-based SDK.

app/sign-in/[[...sign-in]]/page.tsx

import { SignIn } from '@clerk/nextjs'

export default function Page() {
  return (
    <SignIn
      appearance={{
        variables: {
          colorPrimary: '#0000ff', // blue
          colorForeground: '#000000', // black
        },
      }}
    />
  )
}

pages/sign-in.astro

---
import { SignIn } from '@clerk/astro/components'
---

<SignIn
  appearance={{
    colorPrimary: '#0000ff', // blue
    colorForeground: '#000000', // black
  }}
/>

src/pages/sign-in.vue

<script setup lang="ts">
import { SignIn } from '@clerk/vue'
</script>

<template>
  <SignIn :appearance="{ variables: { colorPrimary: '#0000ff', colorForeground: '#000000' } }" />
</template>

pages/sign-in.vue

<script setup lang="ts">
// Components are automatically imported
</script>

<template>
  <SignIn :appearance="{ colorPrimary: '#0000ff', colorForeground: '#000000' }" />
</template>

Using CSS variables

Warning

Please consider this approach with browser compatibility in mind, as it may not work in older browsers. See Browser Compatibility Considerations for details.

You can also use CSS variables to customize the appearance of Clerk components. This approach is particularly useful when:

You have a pre-defined design system with CSS custom properties
You want to support automatic dark/light mode switching
You need to dynamically update colors based on user preferences
You're integrating Clerk into an existing application with established CSS variables

The following example demonstrates how to use CSS variables to customize the appearance of Clerk components, but for maximum browser compatibility, it's recommended to use direct color values instead. It is written for Next.js App Router but can be adapted for any React-based SDK.

global.css

layout.tsx

/src/app/global.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);
  }
}

/src/app/layout.tsx

import { ClerkProvider } from '@clerk/nextjs'
import './global.css'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <ClerkProvider
      appearance={{
        variables: {
          colorPrimary: 'var(--brand-primary)',
        },
      }}
    >
      <html lang="en">
        <body>{children}</body>
      </html>
    </ClerkProvider>
  )
}

Clerk CSS variables

Clerk exposes native CSS variables if you would prefer to define variables directly in your application's stylesheet. All variables exposed through the appearance object are also exposed as CSS variables; see the properties section for a list of the available variables.

The Clerk CSS variables are prefixed with clerk- and are in kebab-case:

:root {
  --clerk-color-primary: #0000ff; /* colorPrimary */
  --clerk-color-foreground: #000000; /* colorForeground */
}

Edit on GitHub

Last updated on Oct 29, 2025

Variables prop

Feedback

`Variables` prop