clerk-custom-ui

Component Customization

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

Component Customization Options

Task	Documentation
Appearance prop overview	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview
Layout (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',
    },
    layout: {
      logoImageUrl: '/logo.png',
      socialButtonsVariant: 'iconButton',
    },
  }}
/>

variables (colors, typography, borders)

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

layout (structure, logo, social buttons)

Property	Description
logoImageUrl	URL to custom logo
socialButtonsVariant	'blockButton' | 'iconButton' | 'auto'
socialButtonsPlacement	'top' | 'bottom'

shadcn Theme

If the project has components.json (shadcn/ui installed), use the shadcn theme:

import { shadcn } from '@clerk/themes'

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

Also import shadcn CSS in your global.css:

@import 'tailwindcss';
@import '@clerk/themes/shadcn.css';

Workflow

1. Identify customization needs (colors, layout, theme, CSS)
2. WebFetch the appropriate documentation from table above
3. Follow official code examples from the docs
4. Apply appearance prop to your Clerk components

Common Pitfalls

Issue	Solution
Colors not applying	Use colorPrimary not primaryColor
Logo not showing	Put logoImageUrl inside layout: {}
Social buttons wrong	Add socialButtonsVariant: 'iconButton' in layout
Styling not working	Use appearance prop, not direct CSS (unless with bring-your-own-css)