clerk-custom-ui
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.
- License 许可
- MIT
- 最近更新
- 2026-10-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- clerk-custom-ui
- license
- MIT
- metadata
- { "author": "clerk", "version": "2.3.0" }
- description
- 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.
- allowed-tools
- WebFetch
02 资源文件 5
- 参考文档core-2/custom-sign-in.md5.4 KB
- 参考文档core-2/custom-sign-up.md4.6 KB
- 参考文档core-3/custom-sign-in.md9.0 KB
- 参考文档core-3/custom-sign-up.md7.5 KB
- 参考文档core-3/show-component.md3.2 KB
03 SKILL.md 正文
Custom UI
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:
- Custom authentication flows — build your own sign-in/sign-up UI with hooks
- 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
| 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
optionsproperty was namedlayout. Uselayout: { logoImageUrl: '...', socialButtonsVariant: '...' }instead ofoptions.
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):
colorRingandcolorModalBackdroprendered 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, notoptions. Also,showOptionalFieldsdefaulted totrue.
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/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
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/themesand@clerk/themes/shadcn.css:import { shadcn } from '@clerk/themes'@import '@clerk/themes/shadcn.css';
Workflow
- Identify customization needs (custom flow or appearance)
- For custom flows: check SDK version → read appropriate
core-2/orcore-3/reference - For appearance: WebFetch the appropriate documentation from table above
- 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 installclerk-nextjs-patterns- Next.js patternsclerk-orgs- B2B organizations
04 同仓库更多 Skills
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall.
gemini-vision-fallback
Vision fallback: Gemini REST API if vision_analyze blocked.
twitter-cli
Use twitter-cli for ALL Twitter/X operations — reading tweets, posting, replying, quoting, liking, retweeting, following, searching, user lookups. Invoke whenever user requests any Twitter interaction.
prism-scan
Structural analysis through dynamically generated cognitive lenses. Generates the optimal analytical lens for the specific code/artifact, then executes it. Finds conservation laws, structural invariants, and concrete bugs that vanilla analysis misses. Use on any code file, system design, or text artifact.
prism-reflect
Constraint transparency: analyzes an artifact structurally, then analyzes what its own analysis concealed. Produces a conservation law AND a constraint report showing what was maximized, what was sacrificed, and what to investigate next. The only AI skill that knows what it can't see.
prism-full
Full Prism: multi-pass structural analysis with mandatory adversarial self-correction. Designs custom analytical passes, executes them with chaining, then attacks its own findings before synthesizing. Use for maximum depth on important code or artifacts.