mihaicrisan04/clerk-custom-ui

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

| Task | Core 2 | Current | | -------------------------- | ------------------------------------------------ | -------------------------- | | Custom sign-in (useSignIn) | core-2/custom-sign-in.md | core-3/custom-sign-in.md | | Custom sign-up (useSignUp) | core-2/custom-sign-up.md | core-3/custom-sign-up.md | | <Show> component | (use <SignedIn>, <SignedOut>, <Protect>) | core-3/show-component.md |

---

Appearance Customization

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

Component Customization Options

| Task | Documentation | | ---------------------------------- | ----------------------------------------------------------------------------------------- | | Appearance prop overview | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview | | Options (structure, logo, buttons) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout | | Themes (pre-built dark/light) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes | | Variables (colors, fonts, spacing) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables | | CAPTCHA configuration | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha | | Bring your own CSS | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css |

Appearance Pattern

<SignIn
  appearance={{
    variables: {
      colorPrimary: '#0000ff',
      borderRadius: '0.5rem',
    },
    options: {
      logoImageUrl: '/logo.png',
      socialButtonsVariant: 'iconButton',
    },
  }}
/>

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

variables (colors, typography, borders)

| Property | Description | | ----------------- | ----------------------------------- | | colorPrimary | Primary color throughout | | colorBackground | Background color | | borderRadius | Border radius (default: 0.375rem) |

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)

| Property | Description | | ------------------------ | --------------------------------------------- | | logoImageUrl | URL to custom logo | | socialButtonsVariant | 'blockButton' | 'iconButton' | 'auto' | | socialButtonsPlacement | 'top' | 'bottom' | | showOptionalFields | Show optional fields (default: false) |

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:

npm install @clerk/ui

import { dark } from '@clerk/ui/themes'

<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:

import { dark, neobrutalism } from '@clerk/ui/themes'

<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:

import { shadcn } from '@clerk/ui/themes'

<ClerkProvider appearance={{ theme: shadcn }} />

Also import shadcn CSS in your global styles:

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

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

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

@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

| Issue | Solution | | ---------------------------- | --------------------------------------------------------------------------------------------- | | Colors not applying | Use colorPrimary not primaryColor | | Logo not showing | Put logoImageUrl inside options: {} (or layout: {} in Core 2) | | Social buttons wrong | Add socialButtonsVariant: 'iconButton' in options (or layout in Core 2) | | Styling not working | Use appearance prop, not direct CSS (unless with bring-your-own-css) | | Hook returns different shape | Check SDK version — Core 2 and current have completely different useSignIn/useSignUp APIs |