自定义 UI
前置条件:确保
ClerkProvider已包裹你的应用。参见clerk-setup技能。版本:检查
package.json中的 SDK 版本 —— 参见clerk技能的版本表。这将决定下方使用的自定义流程参考文件。
本技能涵盖两方面内容:
- 自定义认证流程 —— 使用钩子构建你自己的登录/注册 UI
- 外观定制 —— 主题化、样式化和品牌化 Clerk 的预构建组件
你需要什么?
| 任务 | 参考文件 |
|---|---|
| 自定义登录(Core 2 / LTS) | core-2/custom-sign-in.md |
| 自定义注册(Core 2 / LTS) | core-2/custom-sign-up.md |
| 自定义登录(当前 SDK v7+) | core-3/custom-sign-in.md |
| 自定义注册(当前 SDK v7+) | core-3/custom-sign-up.md |
| 显示组件模式(当前 SDK) | core-3/show-component.md |
自定义流程参考文件
| 任务 | Core 2 | 当前版本 |
|---|---|---|
| 自定义登录(useSignIn) | core-2/custom-sign-in.md | 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属性名为layout。应使用layout: { logoImageUrl: '...', socialButtonsVariant: '...' }替代options。
变量(颜色、排版、边框)
| 属性 | 描述 |
|---|---|
colorPrimary | 全局主色 |
colorBackground | 背景颜色 |
borderRadius | 边框圆角(默认:0.375rem) |
透明度变化: colorRing 和 colorModalBackdrop 现在以全不透明度渲染。如果需要透明度,请使用显式 rgba() 值。
仅限 Core 2(当前 SDK 请跳过):
colorRing和colorModalBackdrop默认以 15% 不透明度渲染。
选项(结构、Logo、社交按钮)
| 属性 | 描述 |
|---|---|
logoImageUrl | 自定义 Logo 的 URL |
socialButtonsVariant | 'blockButton' | 'iconButton' | 'auto' |
socialButtonsPlacement | 'top' | 'bottom' |
showOptionalFields | 显示可选字段(默认:false) |
仅限 Core 2(当前 SDK 请跳过): 此属性名为
layout,而非options。另外,showOptionalFields默认值为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
shadcn 主题
重要: 如果项目中有
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';
工作流程
- 确定定制需求(自定义流程或外观)
- 对于自定义流程:检查 SDK 版本 → 阅读对应的
core-2/或core-3/参考文件 - 对于外观:通过网络获取上表中相应的文档
- 将外观属性应用于你的 Clerk 组件,或使用钩子构建自定义流程
常见陷阱
| 问题 | 解决方案 |
|---|---|
| 颜色未生效 | 使用 colorPrimary 而非 primaryColor |
| Logo 未显示 | 将 logoImageUrl 放在 options: {}(或 Core 2 中的 layout: {})内 |
| 社交按钮显示异常 | 在 options(或 Core 2 中的 layout)中添加 socialButtonsVariant: 'iconButton' |
| 样式未生效 | 使用 appearance 属性,而非直接 CSS(除非使用自带 CSS) |
| 钩子返回值结构不同 | 检查 SDK 版本 —— Core 2 和当前版本的 useSignIn/useSignUp API 完全不同 |
参见
clerk-setup- 初始 Clerk 安装clerk-nextjs-patterns- Next.js 模式clerk-orgs- B2B 组织