Generated banner for Clerk Custom UI
Generated logo for Clerk Custom UI

Clerk Custom UI

ClerkOfficialCreated by clerk

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found

From the author

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.
— the description by clerk

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides guidance on customizing the authentication experience provided by Clerk. It covers two primary areas: building custom sign-in and sign-up flows using React hooks, and styling pre-built Clerk components to match brand requirements. The skill distinguishes between Core 2 and current SDK versions, ensuring developers apply the correct properties, hooks, and theme imports for their specific environment.

What it does

  • Provides instructions for building custom authentication flows with useSignIn and useSignUp hooks.
  • Explains how to use the appearance prop to style Clerk components.
  • Details how to apply pre-built themes like dark, neobrutalism, and shadcn.
  • Guides developers on configuring variables such as colors, typography, and border radius.
  • Outlines how to manage component layout options like logos and social button variants.
  • Offers specific integration steps for projects using the shadcn/ui design system.

When to use it

  • When you need to build a bespoke sign-in or sign-up UI instead of using pre-built components.
  • When you need to align Clerk components with your application's branding and design system.
  • When you need to implement dark mode or specific visual themes for authentication pages.
  • When you are migrating or upgrading between Clerk Core 2 and current SDK versions.

Advantages

  • Ensures visual consistency across your application by supporting custom themes and CSS.
  • Provides clear version-specific guidance to avoid common API pitfalls.
  • Simplifies integration with popular design systems like shadcn/ui.
  • Offers granular control over authentication UI components and flow logic.

Usage examples

“How do I change the primary color of my Clerk sign-in component?”
The agent will explain how to use the appearance prop with the variables object to set the colorPrimary property.
“How can I apply the shadcn theme to my Clerk components?”
The agent will provide the necessary import statements for the shadcn theme and the required CSS import for your global stylesheet.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/clerk/clerk-custom-ui/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip clerk-custom-ui.zip -d .agents/skills

Documentation by clerk

Custom UI

Prerequisite: Ensure ClerkProvider wraps your app. See clerk-setup skill.

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

What Do You Need?

TaskReference
Custom sign-in (Core 2 / LTS)core-2/custom-sign-in.md
Custom sign-up (Core 2 / LTS)core-2/custom-sign-up.md
Custom sign-in (Current SDK v7+)core-3/custom-sign-in.md
Custom sign-up (Current SDK v7+)core-3/custom-sign-up.md
Show component pattern (Current SDK)core-3/show-component.md

Custom Flow References

TaskCore 2Current
Custom sign-in (useSignIn)core-2/custom-sign-in.mdcore-3/custom-sign-in.md
Custom sign-up (useSignUp)core-2/custom-sign-up.mdcore-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
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)
PropertyDescription
colorPrimaryPrimary color throughout
colorBackgroundBackground color
borderRadiusBorder 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)
PropertyDescription
logoImageUrlURL to custom logo
socialButtonsVariant'blockButton' | 'iconButton' | 'auto'
socialButtonsPlacement'top' | 'bottom'
showOptionalFieldsShow 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

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 above

  4. Apply appearance prop to your Clerk components or build custom flow with hooks

Common Pitfalls

IssueSolution
Colors not applyingUse colorPrimary not primaryColor
Logo not showingPut logoImageUrl inside options: {} (or layout: {} in Core 2)
Social buttons wrongAdd socialButtonsVariant: 'iconButton' in options (or layout in Core 2)
Styling not workingUse appearance prop, not direct CSS (unless with bring-your-own-css)
Hook returns different shapeCheck SDK version — Core 2 and current have completely different useSignIn/useSignUp APIs

See Also

  • clerk-setup - Initial Clerk install

  • clerk-nextjs-patterns - Next.js patterns

  • clerk-orgs - B2B organizations

Files

core-2/custom-sign-up.md

Custom Sign-Up Flow (Core 2)

This document covers the older SDK (@clerk/nextjs v5–v6, @clerk/clerk-react v5–v6, @clerk/clerk-expo v1–v2). For the current SDK, see core-3/custom-sign-up.md.

Build a custom sign-up experience using the useSignUp() hook.

Hook API

import { useSignUp } from '@clerk/nextjs' // or @clerk/clerk-react, @clerk/clerk-expo

const { signUp, isLoaded, setActive } = useSignUp()
PropertyTypeDescription
signUpSignUpSign-up object with methods
isLoadedbooleanWhether the hook has loaded
setActive(params) => PromiseSets the active session

Sign-Up Flow

1. Create Sign-Up
const result = await signUp.create({
  emailAddress: '[email protected]',
  password: 'securePassword123',
  firstName: 'Jane',  // optional
  lastName: 'Doe',    // optional
})
2. Prepare Verification

Send a verification code to the user's email or phone:

await signUp.prepareVerification({
  strategy: 'email_code', // or 'phone_code', 'email_link'
})
3. Attempt Verification

Verify the code the user received:

const result = await signUp.attemptVerification({
  strategy: 'email_code',
  code: '123456',
})
4. Finalize

Set the active session after successful sign-up:

await setActive({ session: signUp.createdSessionId })
SSO (OAuth)
await signUp.authenticateWithRedirect({
  strategy: 'oauth_google',
  redirectUrl: '/sso-callback',
  redirectUrlComplete: '/',
})

Error Handling

Use try/catch with isClerkAPIResponseError():

import { isClerkAPIResponseError } from '@clerk/nextjs/errors'

try {
  await signUp.create({ emailAddress, password })
} catch (err) {
  if (isClerkAPIResponseError(err)) {
    err.errors.forEach((e) => {
      console.log(e.code)        // e.g. 'form_password_pwned'
      console.log(e.message)     // Human-readable message
      console.log(e.longMessage) // Detailed message
    })
  }
}

Complete Example: Email/Password with Email Verification

'use client'
import { useState } from 'react'
import { useSignUp } from '@clerk/nextjs'
import { isClerkAPIResponseError } from '@clerk/nextjs/errors'
import { useRouter } from 'next/navigation'

export default function SignUpPage() {
  const { signUp, isLoaded, setActive } = useSignUp()
  const router = useRouter()

  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const [code, setCode] = useState('')
  const [step, setStep] = useState<'register' | 'verify'>('register')
  const [error, setError] = useState('')

  if (!isLoaded) return <div>Loading...</div>

  async function handleRegister(e: React.FormEvent) {
    e.preventDefault()
    setError('')

    try {
      await signUp.create({ emailAddress: email, password })
      await signUp.prepareVerification({ strategy: 'email_code' })
      setStep('verify')
    } catch (err) {
      if (isClerkAPIResponseError(err)) {
        setError(err.errors[0]?.message || 'Sign up failed')
      }
    }
  }

  async function handleVerify(e: React.FormEvent) {
    e.preventDefault()
    setError('')

    try {
      const result = await signUp.attemptVerification({
        strategy: 'email_code',
        code,
      })

      if (result.status === 'complete') {
        await setActive({ session: result.createdSessionId })
        router.push('/')
      }
    } catch (err) {
      if (isClerkAPIResponseError(err)) {
        setError(err.errors[0]?.message || 'Verification failed')
      }
    }
  }

  if (step === 'verify') {
    return (
      <form onSubmit={handleVerify}>
        <p>Check your email for a verification code.</p>
        <input
          type="text"
          value={code}
          onChange={(e) => setCode(e.target.value)}
          placeholder="Verification code"
        />
        {error && <p>{error}</p>}
        <button type="submit">Verify Email</button>
      </form>
    )
  }

  return (
    <form onSubmit={handleRegister}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
      />
      {error && <p>{error}</p>}
      <button type="submit">Sign Up</button>
    </form>
  )
}

Docs

Requirements and compatibility

Written for: Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Names Claude Code tools, Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
clerk
Publisher
Clerk (Official)
Source
clerk/skills · skills/clerk-custom-ui · commit c5d2c0d
Licence
MIT License (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by clerk.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download clerk-custom-ui.zip