--- id: sm-clerk-custom-ui name: "clerk-custom-ui" url: https://skills.yangsir.net/skill/sm-clerk-custom-ui author: clerk domain: ai-frontend-engineering tags: ["clerk", "frontend-customization", "ui/ux-design", "component-libraries", "theming"] install_count: 20600 rating: 4.60 (52 reviews) github: https://github.com/clerk/skills --- # clerk-custom-ui > 掌握Clerk前端自定义UI开发，利用AI技能增强Clerk界面，提供个性化用户体验和品牌一致性。 **Stats**: 20,600 installs · 4.6/5 (52 reviews) ## Before / After 对比 ### 轻松定制Clerk用户界面 ## Readme # clerk-custom-ui # Custom UI **Prerequisite**: Ensure `ClerkProvider` wraps your app. See `setup/`. **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: - **Custom authentication flows** — build your own sign-in/sign-up UI with hooks - **Appearance customization** — theme, style, and brand Clerk's pre-built components ## 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` `` component *(use ``, ``, ``)* `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](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](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](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](https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables) CAPTCHA configuration [https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha](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](https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css) ### Appearance Pattern ``` ``` **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' ``` **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' ``` **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 (HIGH PRIORITY) **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' ``` 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 - Identify customization needs (custom flow or appearance) - For custom flows: check SDK version → read appropriate `core-2/` or `core-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 Weekly Installs2.2KRepository[clerk/skills](https://github.com/clerk/skills)GitHub Stars27First SeenJan 30, 2026Security Audits[Gen Agent Trust HubPass](/clerk/skills/clerk-custom-ui/security/agent-trust-hub)[SocketPass](/clerk/skills/clerk-custom-ui/security/socket)[SnykPass](/clerk/skills/clerk-custom-ui/security/snyk)Installed oncodex2.0Kopencode2.0Kgithub-copilot1.9Kgemini-cli1.9Kamp1.9Kkimi-cli1.9K --- *Source: https://skills.yangsir.net/skill/sm-clerk-custom-ui* *Markdown mirror: https://skills.yangsir.net/api/skill/sm-clerk-custom-ui/markdown*