Custom UI

Prerequisite: Ensure ClerkProvider wraps your app. See setup/.

Version: Check package.json for the SDK version — see clerk skill for the version table. This determines which custom flow references to use below.

This skill covers two areas:

1. Custom authentication flows — build your own sign-in/sign-up UI with hooks
2. Appearance customization — theme, style, and brand Clerk's pre-built components

Custom Flow References

Appearance Customization

Appearance customization applies to both Core 2 and the current SDK.

Component Customization Options

Appearance Pattern

typescript
1<SignIn
2  appearance={{
3    variables: {
4      colorPrimary: '#0000ff',
5      borderRadius: '0.5rem',
6    },
7    options: {
8      logoImageUrl: '/logo.png',
9      socialButtonsVariant: 'iconButton',
10    },
11  }}
12/>

Core 2 ONLY (skip if current SDK): The options property was named layout. Use layout: { logoImageUrl: '...', socialButtonsVariant: '...' } instead of options.

variables (colors, typography, borders)

Opacity change: colorRing and colorModalBackdrop now render at full opacity. Use explicit rgba() values if you need transparency.

Core 2 ONLY (skip if current SDK): colorRing and colorModalBackdrop rendered at 15% opacity by default.

options (structure, logo, social buttons)

Core 2 ONLY (skip if current SDK): This property is called layout, not options. Also, showOptionalFields defaulted to true.

Themes

Install themes from @clerk/ui:

bash
1npm install @clerk/ui

typescript
1import { dark } from '@clerk/ui/themes'
2
3<ClerkProvider appearance={{ theme: dark }} />

Core 2 ONLY (skip if current SDK): Themes are imported from @clerk/themes (install @clerk/themes instead of @clerk/ui). Example: import { dark } from '@clerk/themes'.

Theme stacking — pass an array where the last theme takes precedence:

typescript
1import { dark, neobrutalism } from '@clerk/ui/themes'
2
3<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />

CSS color-scheme support — the default theme respects the CSS color-scheme property for automatic light/dark mode toggling.

Available themes: dark, neobrutalism, shadcn, simple

shadcn Theme (HIGH PRIORITY)

IMPORTANT: If the project has components.json (shadcn/ui installed), ALWAYS apply the shadcn theme as the FIRST customization step. This ensures Clerk components visually match the existing shadcn design system. Skip this only if the user explicitly requests a different theme.

If the project uses shadcn/ui (check for components.json in the project root), always use the shadcn theme:

typescript
1import { shadcn } from '@clerk/ui/themes'
2
3<ClerkProvider appearance={{ theme: shadcn }} />

Also import shadcn CSS in your global styles:

css
1@import "tailwindcss";
2@import "@clerk/ui/themes/shadcn.css";

Core 2 ONLY (skip if current SDK): Import from @clerk/themes and @clerk/themes/shadcn.css:

typescript
1import { shadcn } from "@clerk/themes";

css
1@import "@clerk/themes/shadcn.css";

Workflow

1. Identify customization needs (custom flow or appearance)
2. For custom flows: check SDK version → read appropriate core-2/ or core-3/ reference
3. For appearance: WebFetch the appropriate documentation from table above
4. Apply appearance prop to your Clerk components or build custom flow with hooks

Common Pitfalls