自訂 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。
元件客製化選項
Appearance 模式
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff',
borderRadius: '0.5rem',
},
options: {
logoImageUrl: '/logo.png',
socialButtonsVariant: 'iconButton',
},
}}
/>
僅限 Core 2 (若為當前 SDK 請略過):
options屬性命名為layout。請使用layout: { logoImageUrl: '...', socialButtonsVariant: '...' }而非options。
variables (顏色、排版、邊框)
| 屬性 | 說明 |
|---|---|
colorPrimary | 主要顏色,貫穿全站 |
colorBackground | 背景顏色 |
borderRadius | 邊框圓角 (預設為 0.375rem) |
透明度變更: colorRing 與 colorModalBackdrop 現在以完全不透明度呈現。若需透明度效果,請使用明確的 rgba() 值。
僅限 Core 2 (若為當前 SDK 請略過):
colorRing與colorModalBackdrop預設以 15% 不透明度呈現。
options (結構、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/參考文件 - 若為外觀:使用 WebFetch 取得上方表格中的對應文件
- 將 appearance prop 套用至您的 Clerk 元件,或使用掛鉤建立自訂流程
常見陷阱
| 問題 | 解決方案 |
|---|---|
| 顏色未生效 | 使用 colorPrimary 而非 primaryColor |
| Logo 未顯示 | 將 logoImageUrl 放入 options: {} (或 Core 2 中的 layout: {}) |
| 社交按鈕顯示異常 | 在 options (或 Core 2 中的 layout) 中加入 socialButtonsVariant: 'iconButton' |
| 樣式未套用 | 使用 appearance prop,而非直接 CSS (除非搭配 bring-your-own-css) |
| 掛鉤回傳結構不同 | 檢查 SDK 版本 — Core 2 與當前版本的 useSignIn/useSignUp API 完全不同 |
另請參閱
clerk-setup— 初始 Clerk 安裝clerk-nextjs-patterns— Next.js 模式clerk-orgs— B2B 組織