カスタムUI
前提条件:
ClerkProviderがアプリをラップしていることを確認してください。clerk-setupスキルを参照してください。バージョン:
package.jsonでSDKバージョンを確認してください — バージョンテーブルはclerkスキルを参照してください。これにより、以下で使用するカスタムフローリファレンスが決まります。
このスキルは以下の2つの領域をカバーします:
- カスタム認証フロー — フックを使用して独自のサインイン/サインアップUIを構築
- 外観カスタマイズ — Clerkのビルトインコンポーネントのテーマ、スタイル、ブランディング
何が必要ですか?
| タスク | リファレンス |
|---|---|
| カスタムサインイン(Core 2 / LTS) | core-2/custom-sign-in.md |
| カスタムサインアップ(Core 2 / LTS) | core-2/custom-sign-up.md |
| カスタムサインイン(Current SDK v7+) | core-3/custom-sign-in.md |
| カスタムサインアップ(Current SDK v7+) | core-3/custom-sign-up.md |
| コンポーネントパターンの表示(Current SDK) | core-3/show-component.md |
カスタムフローリファレンス
| タスク | Core 2 | Current |
|---|---|---|
| カスタムサインイン(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とCurrent SDKの両方に適用されます。
コンポーネントカスタマイズオプション
appearance パターン
<SignIn
appearance={{
variables: {
colorPrimary: '#0000ff',
borderRadius: '0.5rem',
},
options: {
logoImageUrl: '/logo.png',
socialButtonsVariant: 'iconButton',
},
}}
/>
Core 2 のみ(Current SDKの場合はスキップ):
optionsプロパティは以前layoutという名前でした。optionsの代わりにlayout: { logoImageUrl: '...', socialButtonsVariant: '...' }を使用してください。
variables(色、タイポグラフィ、境界線)
| プロパティ | 説明 |
|---|---|
colorPrimary | 全体の主要色 |
colorBackground | 背景色 |
borderRadius | 境界線の半径(デフォルト: 0.375rem) |
不透明度の変更: colorRing と colorModalBackdrop は現在、完全な不透明度でレンダリングされます。透明度が必要な場合は、明示的に rgba() 値を使用してください。
Core 2 のみ(Current SDKの場合はスキップ):
colorRingとcolorModalBackdropはデフォルトで15%の不透明度でレンダリングされていました。
options(構造、ロゴ、ソーシャルボタン)
| プロパティ | 説明 |
|---|---|
logoImageUrl | カスタムロゴのURL |
socialButtonsVariant | 'blockButton' | 'iconButton' | 'auto' |
socialButtonsPlacement | 'top' | 'bottom' |
showOptionalFields | オプションフィールドを表示(デフォルト: false) |
Core 2 のみ(Current SDKの場合はスキップ): このプロパティは
optionsではなくlayoutと呼ばれます。また、showOptionalFieldsのデフォルトはtrueでした。
テーマ
@clerk/ui からテーマをインストール:
npm install @clerk/ui
import { dark } from '@clerk/ui/themes'
<ClerkProvider appearance={{ theme: dark }} />
Core 2 のみ(Current SDKの場合はスキップ): テーマは
@clerk/themesからインポートします(@clerk/uiではなく@clerk/themesをインストール)。例: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 のみ(Current SDKの場合はスキップ):
@clerk/themesと@clerk/themes/shadcn.cssからインポート:import { shadcn } from '@clerk/themes'@import '@clerk/themes/shadcn.css';
ワークフロー
- カスタマイズのニーズを特定する(カスタムフローまたは外観)
- カスタムフローの場合: SDKバージョンを確認 → 適切な
core-2/またはcore-3/リファレンスを読む - 外観の場合: 上記の表から適切なドキュメントをWebFetchする
- Clerkコンポーネントにappearanceプロパティを適用するか、フックを使ってカスタムフローを構築する
よくある落とし穴
| 問題 | 解決策 |
|---|---|
| 色が適用されない | primaryColor ではなく colorPrimary を使用する |
| ロゴが表示されない | logoImageUrl を options: {}(Core 2の場合は layout: {})内に配置する |
| ソーシャルボタンがおかしい | options(Core 2の場合は layout)内に socialButtonsVariant: 'iconButton' を追加する |
| スタイリングが効かない | 直接CSSではなくappearanceプロパティを使用する(bring-your-own-cssを使用する場合を除く) |
| フックの戻り値の形状が異なる | SDKバージョンを確認 — Core 2とCurrentでは useSignIn/useSignUp APIが完全に異なる |
関連項目
clerk-setup- Clerkの初期インストールclerk-nextjs-patterns- Next.jsパターンclerk-orgs- B2B組織