feat(clerk-js,themes,types): Introduce Clerk CSS variables #6275

alexcarpenter · 2025-07-09T17:26:14Z

Description

This PR exposes the ability to theme Clerk components using CSS custom properties, avoiding the need to pass variables into the appearance variables prop.

All of the variables support an accompanying clerk prefixed CSS custom property. The CSS custom property is using kebab casing.

e.g. colorPrimary = --clerk-color-primary.

:root {
  --clerk-color-primary: #6D47FF;
  --clerk-color-muted-foreground: #999999;
}

The equivalent using the appearance prop would be:

<ClerkProvider
  appearance={{
    variables: {
      colorPrimary: '#6D47FF',
      colorMutedForeground: '#999999',
    }
  }}
/>

Deprecated variables

This PR also makes some updates to current variable names, with deprecation notices to migrate to the updated keys.

Deprecated	New
`colorText`	`colorForeground`
`colorTextOnPrimaryBackground`	`colorPrimaryForeground`
`colorTextSecondary`	`colorMutedForeground`
`spacingUnit`	`spacing`
`colorInputText`	`colorInputForeground`
`colorInputBackground`	`colorInput`

New variables

colorRing - The color of the ring when an interactive element is focused.
colorMuted - The background color for elements of lower importance, eg: a muted background.
colorShadow - The base shadow color used in the components.
colorBorder - The base border color used in the components.
colorModalBackdrop - The background color of the modal backdrop.

Resolves USER-2202

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Introduced support for CSS custom properties, enabling enhanced theming and customization of Clerk components via standard CSS variables.
- Added new theme variables for focus ring, muted background, shadow, and border colors.
- Extended font size support to accept scalable font size objects for flexible typography.
Refactor
- Renamed color and spacing variables for improved clarity and consistency across components and themes.
- Transitioned from static to dynamic generation of colors, spacing, shadows, and typography scales for better theme adaptability.
- Improved font size and weight scaling to support flexible typography customization.
- Enhanced CSS variable resolution to support nested fallbacks and introduced a utility for consistent CSS variable usage.
- Updated border radius and spacing units to use CSS variables for dynamic theming.
- Incorporated shadow generation into internal theme creation for richer styling options.
Style
- Updated UI components to use new color and spacing tokens, enhancing visual consistency and alignment with updated themes.
- Refined component styling with updated color tokens for borders, text, backgrounds, and shadows.
Documentation
- Added documentation for new and deprecated CSS variables, including usage examples and migration guidance.
Tests
- Updated and expanded test coverage to incorporate new variable names and theming utilities.
- Added comprehensive tests for nested CSS variable resolution and CSS variable utilities.

changeset-bot · 2025-07-09T17:26:20Z

🦋 Changeset detected

Latest commit: 4b1bada

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 22 packages

Name	Type
@clerk/clerk-js	Minor
@clerk/themes	Minor
@clerk/types	Minor
@clerk/chrome-extension	Patch
@clerk/clerk-expo	Patch
@clerk/clerk-react	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/shared	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-07-09T17:26:20Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 15, 2025 7:13pm

alexcarpenter · 2025-07-11T17:04:16Z

!snapshot

…le-utilities-for-current-variables

clerk-cookie · 2025-07-11T17:07:41Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.1.7-snapshot.v20250711170548
@clerk/astro	2.10.4-snapshot.v20250711170548
@clerk/backend	2.4.2-snapshot.v20250711170548
@clerk/chrome-extension	2.5.5-snapshot.v20250711170548
@clerk/clerk-js	5.71.1-snapshot.v20250711170548
@clerk/elements	0.23.39-snapshot.v20250711170548
@clerk/clerk-expo	2.14.4-snapshot.v20250711170548
@clerk/expo-passkeys	0.3.16-snapshot.v20250711170548
@clerk/express	1.7.6-snapshot.v20250711170548
@clerk/fastify	2.4.6-snapshot.v20250711170548
@clerk/localizations	3.18.1-snapshot.v20250711170548
@clerk/nextjs	6.24.1-snapshot.v20250711170548
@clerk/nuxt	1.7.7-snapshot.v20250711170548
@clerk/clerk-react	5.33.1-snapshot.v20250711170548
@clerk/react-router	1.7.1-snapshot.v20250711170548
@clerk/remix	4.9.1-snapshot.v20250711170548
@clerk/shared	3.11.1-snapshot.v20250711170548
@clerk/tanstack-react-start	0.19.1-snapshot.v20250711170548
@clerk/testing	1.10.0-snapshot.v20250711170548
@clerk/themes	2.2.56-snapshot.v20250711170548
@clerk/types	4.64.1-snapshot.v20250711170548
@clerk/vue	1.8.14-snapshot.v20250711170548

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.1.7-snapshot.v20250711170548 --save-exact

@clerk/astro

npm i @clerk/astro@2.10.4-snapshot.v20250711170548 --save-exact

@clerk/backend

npm i @clerk/backend@2.4.2-snapshot.v20250711170548 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@2.5.5-snapshot.v20250711170548 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.71.1-snapshot.v20250711170548 --save-exact

@clerk/elements

npm i @clerk/elements@0.23.39-snapshot.v20250711170548 --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@2.14.4-snapshot.v20250711170548 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@0.3.16-snapshot.v20250711170548 --save-exact

@clerk/express

npm i @clerk/express@1.7.6-snapshot.v20250711170548 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.4.6-snapshot.v20250711170548 --save-exact

@clerk/localizations

npm i @clerk/localizations@3.18.1-snapshot.v20250711170548 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@6.24.1-snapshot.v20250711170548 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@1.7.7-snapshot.v20250711170548 --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.33.1-snapshot.v20250711170548 --save-exact

@clerk/react-router

npm i @clerk/react-router@1.7.1-snapshot.v20250711170548 --save-exact

@clerk/remix

npm i @clerk/remix@4.9.1-snapshot.v20250711170548 --save-exact

@clerk/shared

npm i @clerk/shared@3.11.1-snapshot.v20250711170548 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@0.19.1-snapshot.v20250711170548 --save-exact

@clerk/testing

npm i @clerk/testing@1.10.0-snapshot.v20250711170548 --save-exact

@clerk/themes

npm i @clerk/themes@2.2.56-snapshot.v20250711170548 --save-exact

@clerk/types

npm i @clerk/types@4.64.1-snapshot.v20250711170548 --save-exact

@clerk/vue

npm i @clerk/vue@1.8.14-snapshot.v20250711170548 --save-exact

…6289)

… vars

brkalow

👏

brkalow · 2025-07-15T14:28:03Z

packages/clerk-js/src/ui/foundations/sizes.ts

+  xl: '2', // 2.0
+} as const);
+
+const radiiDefaultVar = clerkCssVar('border-radius', '0.375rem');


I don't think I've ever seen radii in code... 😄

…le-utilities-for-current-variables

…s-for-current-variables' of github.com:clerk/javascript into alexcarpenter/user-2202-add-clerk-css-variable-utilities-for-current-variables

alexcarpenter · 2025-07-15T17:11:33Z

!snapshot

clerk-cookie · 2025-07-15T17:14:04Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.1.8-snapshot.v20250715171210
@clerk/astro	2.10.5-snapshot.v20250715171210
@clerk/backend	2.4.3-snapshot.v20250715171210
@clerk/chrome-extension	2.5.6-snapshot.v20250715171210
@clerk/clerk-js	5.73.0-snapshot.v20250715171210
@clerk/elements	0.23.40-snapshot.v20250715171210
@clerk/clerk-expo	2.14.5-snapshot.v20250715171210
@clerk/expo-passkeys	0.3.17-snapshot.v20250715171210
@clerk/express	1.7.7-snapshot.v20250715171210
@clerk/fastify	2.4.7-snapshot.v20250715171210
@clerk/localizations	3.19.0-snapshot.v20250715171210
@clerk/nextjs	6.25.1-snapshot.v20250715171210
@clerk/nuxt	1.7.8-snapshot.v20250715171210
@clerk/clerk-react	5.35.0-snapshot.v20250715171210
@clerk/react-router	1.8.1-snapshot.v20250715171210
@clerk/remix	4.10.1-snapshot.v20250715171210
@clerk/shared	3.12.1-snapshot.v20250715171210
@clerk/tanstack-react-start	0.20.1-snapshot.v20250715171210
@clerk/testing	1.10.1-snapshot.v20250715171210
@clerk/themes	2.3.0-snapshot.v20250715171210
@clerk/types	4.66.0-snapshot.v20250715171210
@clerk/vue	1.8.15-snapshot.v20250715171210

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.1.8-snapshot.v20250715171210 --save-exact

@clerk/astro

npm i @clerk/astro@2.10.5-snapshot.v20250715171210 --save-exact

@clerk/backend

npm i @clerk/backend@2.4.3-snapshot.v20250715171210 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@2.5.6-snapshot.v20250715171210 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.73.0-snapshot.v20250715171210 --save-exact

@clerk/elements

npm i @clerk/elements@0.23.40-snapshot.v20250715171210 --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@2.14.5-snapshot.v20250715171210 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@0.3.17-snapshot.v20250715171210 --save-exact

@clerk/express

npm i @clerk/express@1.7.7-snapshot.v20250715171210 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.4.7-snapshot.v20250715171210 --save-exact

@clerk/localizations

npm i @clerk/localizations@3.19.0-snapshot.v20250715171210 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@6.25.1-snapshot.v20250715171210 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@1.7.8-snapshot.v20250715171210 --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.35.0-snapshot.v20250715171210 --save-exact

@clerk/react-router

npm i @clerk/react-router@1.8.1-snapshot.v20250715171210 --save-exact

@clerk/remix

npm i @clerk/remix@4.10.1-snapshot.v20250715171210 --save-exact

@clerk/shared

npm i @clerk/shared@3.12.1-snapshot.v20250715171210 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@0.20.1-snapshot.v20250715171210 --save-exact

@clerk/testing

npm i @clerk/testing@1.10.1-snapshot.v20250715171210 --save-exact

@clerk/themes

npm i @clerk/themes@2.3.0-snapshot.v20250715171210 --save-exact

@clerk/types

npm i @clerk/types@4.66.0-snapshot.v20250715171210 --save-exact

@clerk/vue

npm i @clerk/vue@1.8.15-snapshot.v20250715171210 --save-exact

…le-utilities-for-current-variables

.changeset/cuddly-heads-battle.md

feat(clerk-js): Expose CSS variables for clerk appearance variables

e0e6ef6

clerk-cookie added the clerk-js label Jul 9, 2025

vercel bot deployed to Preview July 9, 2025 17:27 View deployment

handle colorTextSecondary

e246501

vercel bot deployed to Preview July 9, 2025 17:56 View deployment

update sizes and typography foundations

3d4fd36

vercel bot deployed to Preview July 9, 2025 19:15 View deployment

handle types

9a2a9c6

vercel bot deployed to Preview July 9, 2025 19:58 View deployment

alexcarpenter added 2 commits July 9, 2025 16:13

fix exports

d9740c3

fix application logo sizing

be27f20

vercel bot deployed to Preview July 9, 2025 20:14 View deployment

alexcarpenter changed the title ~~feat(clerk-js): Expose CSS variables for clerk appearance variables~~ feat(clerk-js): Introduce Clerk CSS variables for theming Jul 11, 2025

chore(clerk-js,themes,types): Variable migration (#6282)

c8f61e2

clerk-cookie added types themes labels Jul 11, 2025

vercel bot deployed to Preview July 11, 2025 14:42 View deployment

alexcarpenter changed the title ~~feat(clerk-js): Introduce Clerk CSS variables for theming~~ feat(clerk-js): Introduce Clerk CSS custom properties for theming Jul 11, 2025

alexcarpenter changed the title ~~feat(clerk-js): Introduce Clerk CSS custom properties for theming~~ feat(clerk-js): Introduce Clerk CSS variables for theming Jul 11, 2025

Merge branch 'main' into alexcarpenter/user-2202-add-clerk-css-variab…

c65258c

…le-utilities-for-current-variables

vercel bot deployed to Preview July 11, 2025 17:06 View deployment

feat(clerk-js): Expose CSS variables for clerk appearance variables (#…

daac718

…6289)

vercel bot deployed to Preview July 11, 2025 17:39 View deployment

fix card footer background color

f5c57ce

vercel bot deployed to Preview July 11, 2025 18:33 View deployment

simplify

f4bf7cc

vercel bot deployed to Preview July 15, 2025 13:38 View deployment

Update bundlewatch.config.json

0f7cc63

vercel bot deployed to Preview July 15, 2025 13:57 View deployment

tmilewski approved these changes Jul 15, 2025

View reviewed changes

fix: update resolveCSSVariable to be recursive to handle fallback css…

5c0cdb9

… vars

vercel bot deployed to Preview July 15, 2025 14:23 View deployment

Update bundlewatch.config.json

077f7d6

vercel bot deployed to Preview July 15, 2025 14:32 View deployment

brkalow approved these changes Jul 15, 2025

View reviewed changes

update tests

a522c9d

vercel bot deployed to Preview July 15, 2025 14:37 View deployment

lint

876741d

vercel bot deployed to Preview July 15, 2025 14:49 View deployment

Merge branch 'main' into alexcarpenter/user-2202-add-clerk-css-variab…

de632bd

…le-utilities-for-current-variables

vercel bot deployed to Preview July 15, 2025 15:18 View deployment

alexcarpenter added 2 commits July 15, 2025 11:23

Update bundlewatch.config.json

da17e0c

Merge branch 'alexcarpenter/user-2202-add-clerk-css-variable-utilitie…

e6d1ec2

…s-for-current-variables' of github.com:clerk/javascript into alexcarpenter/user-2202-add-clerk-css-variable-utilities-for-current-variables

vercel bot deployed to Preview July 15, 2025 15:24 View deployment

Merge branch 'main' into alexcarpenter/user-2202-add-clerk-css-variab…

590d502

…le-utilities-for-current-variables

vercel bot deployed to Preview July 15, 2025 19:02 View deployment

alexcarpenter commented Jul 15, 2025

View reviewed changes

.changeset/cuddly-heads-battle.md Outdated Show resolved Hide resolved

Update .changeset/cuddly-heads-battle.md

4b1bada

alexcarpenter enabled auto-merge (squash) July 15, 2025 19:12

vercel bot deployed to Preview July 15, 2025 19:13 View deployment

alexcarpenter merged commit 025e304 into main Jul 15, 2025
38 checks passed

alexcarpenter deleted the alexcarpenter/user-2202-add-clerk-css-variable-utilities-for-current-variables branch July 15, 2025 19:23

clerk-cookie mentioned this pull request Jul 15, 2025

ci(repo): Version packages #6308

Merged

jacekradko pushed a commit that referenced this pull request Jul 24, 2025

feat(clerk-js,themes,types): Introduce Clerk CSS variables (#6275)

537baed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(clerk-js,themes,types): Introduce Clerk CSS variables #6275

feat(clerk-js,themes,types): Introduce Clerk CSS variables #6275

Uh oh!

alexcarpenter commented Jul 9, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jul 9, 2025 •

edited

Loading

Uh oh!

vercel bot commented Jul 9, 2025 •

edited

Loading

Uh oh!

alexcarpenter commented Jul 11, 2025

Uh oh!

clerk-cookie commented Jul 11, 2025

Uh oh!

brkalow left a comment

Uh oh!

brkalow Jul 15, 2025

Uh oh!

alexcarpenter commented Jul 15, 2025

Uh oh!

clerk-cookie commented Jul 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

feat(clerk-js,themes,types): Introduce Clerk CSS variables #6275

feat(clerk-js,themes,types): Introduce Clerk CSS variables #6275

Uh oh!

Conversation

alexcarpenter commented Jul 9, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Deprecated variables

New variables

Checklist

Type of change

Summary by CodeRabbit

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexcarpenter commented Jul 11, 2025

Uh oh!

clerk-cookie commented Jul 11, 2025

Uh oh!

brkalow left a comment

Choose a reason for hiding this comment

Uh oh!

brkalow Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

alexcarpenter commented Jul 15, 2025

Uh oh!

clerk-cookie commented Jul 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexcarpenter commented Jul 9, 2025 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jul 9, 2025 •

edited

Loading

vercel bot commented Jul 9, 2025 •

edited

Loading