npx skills add https://github.com/clerk/skills --skill clerk-custom-ui前提条件:确保
ClerkProvider包裹了你的应用。请参阅setup/。版本:查看
package.json中的 SDK 版本 — 请参阅clerk技能中的版本表。这决定了下面应使用哪些自定义流程参考。
此技能涵盖两个领域:
| 任务 | Core 2 | 当前版本 |
|---|---|---|
| 自定义登录 (useSignIn) | core-2/custom-sign-in.md |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
core-3/custom-sign-in.md |
| 自定义注册 (useSignUp) | core-2/custom-sign-up.md | core-3/custom-sign-up.md |
<Show> 组件 | (使用<SignedIn>, <SignedOut>, <Protect>) | core-3/show-component.md |
外观自定义同时适用于 Core 2 和当前版本的 SDK。
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff',
borderRadius: '0.5rem',
},
options: {
logoImageUrl: '/logo.png',
socialButtonsVariant: 'iconButton',
},
}}
/>
仅限 Core 2(当前 SDK 请跳过):
options属性在 Core 2 中名为layout。请使用layout: { logoImageUrl: '...', socialButtonsVariant: '...' }而不是options。
| 属性 | 描述 |
|---|---|
colorPrimary | 全局主色调 |
colorBackground | 背景颜色 |
borderRadius | 边框圆角(默认:0.375rem) |
不透明度变更: colorRing 和 colorModalBackdrop 现在以完全不透明度渲染。如果需要透明度,请使用明确的 rgba() 值。
仅限 Core 2(当前 SDK 请跳过):
colorRing和colorModalBackdrop默认以 15% 的不透明度渲染。
| 属性 | 描述 |
|---|---|
logoImageUrl | 自定义徽标的 URL |
socialButtonsVariant | 'blockButton' |
socialButtonsPlacement | 'top' |
showOptionalFields | 显示可选字段(默认:false) |
仅限 Core 2(当前 SDK 请跳过): 此属性在 Core 2 中名为
layout,而不是options。此外,showOptionalFields在 Core 2 中默认为true。
从 @clerk/ui 安装主题:
npm install @clerk/ui
import { dark } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: dark }} />
仅限 Core 2(当前 SDK 请跳过): 主题从
@clerk/themes导入(请安装@clerk/themes而不是@clerk/ui)。例如:import { dark } from '@clerk/themes'。
主题堆叠 — 传递一个数组,其中最后一个主题具有最高优先级:
import { dark, neobrutalism } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />
CSS color-scheme 支持 — 默认主题遵循 CSS color-scheme 属性,以实现自动的浅色/深色模式切换。
可用主题: dark, neobrutalism, shadcn, simple
重要: 如果项目中有
components.json(已安装 shadcn/ui),始终将 shadcn 主题作为第一个自定义步骤应用。这确保了 Clerk 组件在视觉上与现有的 shadcn 设计系统相匹配。仅当用户明确请求其他主题时才跳过此步骤。
如果项目使用 shadcn/ui(检查项目根目录下是否有 components.json),始终使用 shadcn 主题:
import { shadcn } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: shadcn }} />
同时在你的全局样式中导入 shadcn CSS:
@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';
仅限 Core 2(当前 SDK 请跳过): 从
@clerk/themes和@clerk/themes/shadcn.css导入:import { shadcn } from '@clerk/themes' @import '@clerk/themes/shadcn.css';
core-2/ 或 core-3/ 参考文档| 问题 | 解决方案 |
|---|---|
| 颜色未应用 | 使用 colorPrimary 而不是 primaryColor |
| 徽标未显示 | 将 logoImageUrl 放在 options: {} 内(在 Core 2 中是 layout: {}) |
| 社交按钮样式错误 | 在 options 中添加 socialButtonsVariant: 'iconButton'(在 Core 2 中是 layout) |
| 样式不生效 | 使用 appearance 属性,而不是直接使用 CSS(除非使用 bring-your-own-css) |
| 钩子返回不同的结构 | 检查 SDK 版本 — Core 2 和当前版本的 useSignIn/useSignUp API 完全不同 |
每周安装量
1.8K
代码仓库
GitHub 星标数
22
首次出现
2026年1月30日
安全审计
安装于
codex1.6K
opencode1.6K
github-copilot1.5K
gemini-cli1.5K
amp1.5K
kimi-cli1.5K
Prerequisite : Ensure
ClerkProviderwraps your app. Seesetup/.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 | 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' |
socialButtonsPlacement | 'top' |
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] }} />
CSScolor-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) |
Weekly Installs
1.8K
Repository
GitHub Stars
22
First Seen
Jan 30, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex1.6K
opencode1.6K
github-copilot1.5K
gemini-cli1.5K
amp1.5K
kimi-cli1.5K
99,500 周安装
| 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 |