Clerk 自定义 UI：构建个性化登录注册界面与主题样式定制指南

clerk-custom-ui by clerk/skills

2,500 周安装量

30 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/clerk/skills --skill clerk-custom-ui

开发安全

🇨🇳中文介绍

自定义界面

前提条件：确保 ClerkProvider 包裹了你的应用。请参阅 setup/。

版本：查看 package.json 中的 SDK 版本 — 请参阅 clerk 技能中的版本表。这决定了下面应使用哪些自定义流程参考。

此技能涵盖两个领域：

自定义身份验证流程 — 使用钩子构建你自己的登录/注册界面
外观自定义 — 为主题、样式和品牌自定义 Clerk 预构建的组件

自定义流程参考

任务	Core 2	当前版本
自定义登录 (useSignIn)	`core-2/custom-sign-in.md`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

705,000 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

245,300 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

196,800 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

128,699 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

任务	文档
appearance 属性概述	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview
选项（结构、徽标、按钮）	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout
主题（预构建的深色/浅色）	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes
变量（颜色、字体、间距）	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables
CAPTCHA 配置	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha
使用你自己的 CSS	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css

仅限 Core 2（当前 SDK 请跳过）： options 属性在 Core 2 中名为 layout。请使用 layout: { logoImageUrl: '...', socialButtonsVariant: '...' } 而不是 options。

属性	描述
`colorPrimary`	全局主色调
`colorBackground`	背景颜色
`borderRadius`	边框圆角（默认：`0.375rem`）

属性	描述
`logoImageUrl`	自定义徽标的 URL
`socialButtonsVariant`	`'blockButton'`
`socialButtonsPlacement`	`'top'`
`showOptionalFields`	显示可选字段（默认：`false`）

仅限 Core 2（当前 SDK 请跳过）： 此属性在 Core 2 中名为 layout，而不是 options。此外，showOptionalFields 在 Core 2 中默认为 true。

仅限 Core 2（当前 SDK 请跳过）： 主题从 @clerk/themes 导入（请安装 @clerk/themes 而不是 @clerk/ui）。例如：import { dark } from '@clerk/themes'。

仅限 Core 2（当前 SDK 请跳过）： 从 @clerk/themes 和 @clerk/themes/shadcn.css 导入：
import { shadcn } from '@clerk/themes'



@import '@clerk/themes/shadcn.css';

问题	解决方案
颜色未应用	使用 `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 完全不同

🇺🇸English

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`
`<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 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'`
`socialButtonsPlacement`	`'top'`
`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] }} />

CSScolor-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'

<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

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)

Weekly Installs

1.8K

Repository

clerk/skills

GitHub Stars

First Seen

Jan 30, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex1.6K

opencode1.6K

github-copilot1.5K

gemini-cli1.5K

amp1.5K

kimi-cli1.5K

Clerk 自定义 UI：构建个性化登录注册界面与主题样式定制指南

🇨🇳中文介绍

自定义界面

自定义流程参考

相关 Skills

外观自定义

组件自定义选项

外观模式

variables（颜色、排版、边框）

options（结构、徽标、社交按钮）

主题

shadcn 主题（高优先级）

工作流程

常见问题