Variables
prop
The variables
property is used to adjust the general styles of the component's base theme, like colors, backgrounds, and typography.
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
(usecolorForeground
instead)colorTextOnPrimaryBackground
(usecolorPrimaryForeground
instead)colorTextSecondary
(usecolorMutedForeground
instead)spacingUnit
(usespacing
instead)colorInputText
(usecolorInputForeground
instead)colorInputBackground
(usecolorInput
instead)
Usage
You can customize Clerk components by passing an object of variables to the variables
property of the appearance
prop.
Apply variables
to all Clerk components
To customize all Clerk components, pass the variables
property to the appearance
prop of the <ClerkProvider>
component.
In the following example, the primary color is set to blue and the text color is set to black. Because these styles are applied to the <ClerkProvider>
, which wraps the entire application, these styles will be applied to all Clerk components that use the primary color and text color.
import { ClerkProvider } from '@clerk/nextjs'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<ClerkProvider
appearance={{
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
}}
>
<html lang="en">
<body>{children}</body>
</html>
</ClerkProvider>
)
}
import { ClerkProvider } from '@clerk/nextjs'
import type { AppProps } from 'next/app'
function MyApp({ Component, pageProps }: AppProps) {
return (
<ClerkProvider
appearance={{
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
}}
>
<Component {...pageProps} />
</ClerkProvider>
)
}
export default MyApp
import React from 'react'
import './App.css'
import { ClerkProvider } from '@clerk/clerk-react'
if (!process.env.REACT_APP_CLERK_PUBLISHABLE_KEY) {
throw new Error('Missing Publishable Key')
}
const clerkPubKey = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY
function App() {
return (
<ClerkProvider
appearance={{
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
}}
publishableKey={clerkPubKey}
>
<div>Hello from clerk</div>
</ClerkProvider>
)
}
export default App
// Import ClerkApp
import { ClerkApp } from '@clerk/remix'
import type { MetaFunction, LoaderFunction } from '@remix-run/node'
import { Links, LiveReload, Meta, Outlet, Scripts, ScrollRestoration } from '@remix-run/react'
import { rootAuthLoader } from '@clerk/remix/ssr.server'
export const meta: MetaFunction = () => ({
charset: 'utf-8',
title: 'New Remix App',
viewport: 'width=device-width,initial-scale=1',
})
export const loader: LoaderFunction = (args) => rootAuthLoader(args)
function App() {
return (
<html lang="en">
<head>
<Meta />
<Links />
</head>
<body>
<Outlet />
<ScrollRestoration />
<Scripts />
<LiveReload />
</body>
</html>
)
}
export default ClerkApp(App, {
appearance: {
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
},
})
import clerk from '@clerk/astro'
export default defineConfig({
integrations: [
clerk({
appearance: {
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
},
}),
],
})
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')
export default defineNuxtConfig({
modules: ['@clerk/nuxt'],
clerk: {
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 of the <ClerkProvider>
. 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.
import { ClerkProvider } from '@clerk/nextjs'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<ClerkProvider
appearance={{
signIn: {
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
},
}}
>
<html lang="en">
<body>{children}</body>
</html>
</ClerkProvider>
)
}
import { ClerkProvider } from '@clerk/nextjs'
import type { AppProps } from 'next/app'
function MyApp({ Component, pageProps }: AppProps) {
return (
<ClerkProvider
appearance={{
signIn: {
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
},
}}
>
<Component {...pageProps} />
</ClerkProvider>
)
}
export default MyApp
import React from 'react'
import './App.css'
import { ClerkProvider } from '@clerk/clerk-react'
if (!process.env.REACT_APP_CLERK_PUBLISHABLE_KEY) {
throw new Error('Missing Publishable Key')
}
const clerkPubKey = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY
function App() {
return (
<ClerkProvider
appearance={{
signIn: {
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
},
}}
publishableKey={clerkPubKey}
>
<div>Hello from clerk</div>
</ClerkProvider>
)
}
export default App
// Import ClerkApp
import { ClerkApp } from '@clerk/remix'
import type { MetaFunction, LoaderFunction } from '@remix-run/node'
import { Links, LiveReload, Meta, Outlet, Scripts, ScrollRestoration } from '@remix-run/react'
import { rootAuthLoader } from '@clerk/remix/ssr.server'
export const meta: MetaFunction = () => ({
charset: 'utf-8',
title: 'New Remix App',
viewport: 'width=device-width,initial-scale=1',
})
export const loader: LoaderFunction = (args) => rootAuthLoader(args)
function App() {
return (
<html lang="en">
<head>
<Meta />
<Links />
</head>
<body>
<Outlet />
<ScrollRestoration />
<Scripts />
<LiveReload />
</body>
</html>
)
}
export default ClerkApp(App, {
appearance: {
signIn: {
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
},
},
})
import clerk from '@clerk/astro'
export default defineConfig({
integrations: [
clerk({
appearance: {
signIn: {
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
},
},
}),
],
})
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')
export default defineNuxtConfig({
modules: ['@clerk/nuxt'],
clerk: {
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.
import { SignIn } from '@clerk/nextjs'
export default function Page() {
return (
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
}}
/>
)
}
import { SignIn } from '@clerk/nextjs'
const SignInPage = () => (
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
}}
/>
)
export default SignInPage
import { SignIn } from '@clerk/clerk-react'
const SignInPage = () => (
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
}}
/>
)
export default SignInPage
import { SignIn } from '@clerk/remix'
export default function SignInPage() {
return (
<div style={{ border: '2px solid blue', padding: '2rem' }}>
<h1>Sign In route</h1>
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
},
}}
/>
</div>
)
}
---
import { SignIn } from '@clerk/astro/components'
---
<SignIn
appearance={{
colorPrimary: '#0000ff', // blue
colorForeground: '#000000', // black
}}
/>
<script setup lang="ts">
import { SignIn } from '@clerk/vue'
</script>
<template>
<SignIn :appearance="{ variables: { colorPrimary: '#0000ff', colorForeground: '#000000' } }" />
</template>
<script setup lang="ts">
// Components are automatically imported
</script>
<template>
<SignIn :appearance="{ colorPrimary: '#0000ff', colorForeground: '#000000' }" />
</template>
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.
: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);
}
}
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 */
}
Feedback
Last updated on