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.
Prerequisite: Ensure
ClerkProviderwraps your app. Seeclerk-setupskill.Version: Check
package.jsonfor the SDK version — seeclerkskill for the version table. This determines which custom flow references to use below.
This skill covers two areas:
| Task | Reference |
|---|---|
| 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 |
| 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 applies to both Core 2 and the current SDK.
| 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 |
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff',
borderRadius: '0.5rem',
},
options: {
logoImageUrl: '/logo.png',
socialButtonsVariant: 'iconButton',
},
}}
/>
Core 2 ONLY (skip if current SDK): The
optionsproperty was namedlayout. Uselayout: { logoImageUrl: '...', socialButtonsVariant: '...' }instead ofoptions.
| 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):
colorRingandcolorModalBackdroprendered at 15% opacity by default.
| 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, notoptions. Also,showOptionalFieldsdefaulted totrue.
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/themesinstead 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
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/themesand@clerk/themes/shadcn.css:import { shadcn } from "@clerk/themes";@import "@clerk/themes/shadcn.css";
core-2/ or core-3/ reference| 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 |
clerk-setup - Initial Clerk installclerk-nextjs-patterns - Next.js patternsclerk-orgs - B2B organizations