Index of every page on this site: llms.txt
All skills
clerk avatar

/clerk-custom-ui

@95f241a official
by clerkclerk/skills95 stars
6
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/clerk/skills/clerk-custom-ui

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈55 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈7.9k more on demand in 5 files.

Description uses 2.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈220 characters, or 2.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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?

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

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

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

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

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

See Also

  • clerk-setup - Initial Clerk install
  • clerk-nextjs-patterns - Next.js patterns
  • clerk-orgs - B2B organizations

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts9d5 checks · Risk SAFE
  • Gen Agent Trust Hub10d

    This skill provides documentation and code examples for building custom authentication flows and styling Clerk components. It is a legitimate developer tool authored by Clerk and contains no security issues.

  • Socket9d

    No alerts

  • Snyk10d

    Risk: LOW · No issues

  • Runlayer8mo

    7 files scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 95f241a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week
What it can do
Network
metadata
{
  "author": "clerk",
  "version": "2.3.1"
}
All 1 allowed tools
WebFetch
  • React
  • clerk
  • authentication
  • custom-ui
  • hooks
  • theming
  • appearance
  • branding

README badge

README badge for clerk/skills/clerk-custom-ui

Builds custom sign-in and sign-up flows using Clerk's useSignIn and useSignUp hooks, and customizes Clerk component appearance via the appearance prop with themes, colors, fonts, and CSS. Supports both Core 2 and current SDK versions with different API shapes for each.

Generated from the current SKILL.md.

Does this skill work with both Core 2 and the current SDK (v7+)?
Yes. Custom flows have separate references for Core 2 and current SDK because their hook APIs differ. Appearance customization works the same across both, but Core 2 uses `layout` instead of `options` and imports themes from `@clerk/themes` instead of `@clerk/ui/themes`.
Can I use the shadcn theme with Clerk components?
Yes. If your project has `components.json` (shadcn/ui installed), import the shadcn theme from `@clerk/ui/themes` and apply it as your first customization step to ensure visual consistency with your design system.
How do I build a completely custom sign-in form?
Use the `useSignIn` hook with a custom component. The skill includes separate references for Core 2 and current SDK since their APIs differ significantly.
What's the difference between `variables` and `options` in the appearance prop?
`variables` controls colors, typography, and spacing (e.g. `colorPrimary`, `borderRadius`). `options` controls component structure like logo URL and social button layout (note: Core 2 calls this `layout`).
Does this skill require ClerkProvider to be set up first?
Yes. The skill assumes `ClerkProvider` wraps your app. Refer to the `clerk-setup` skill for initial installation if needed.

Generated from the current SKILL.md. These answers refresh after source changes.