カスタム UI

前提条件: ClerkProvider があなたのアプリをラップしていることを確認してください。setup/ を参照してください。

バージョン: package.json で SDK バージョンを確認してください。clerk スキルを参照してバージョンテーブルを確認してください。これにより、以下で使用するカスタムフロー参照が決定されます。

このスキルは 2 つの領域をカバーしています:

1. カスタム認証フロー — フックを使用して独自のサインイン/サインアップ UI を構築
2. アピアランスカスタマイズ — Clerk のプリビルトコンポーネントをテーマ、スタイル、ブランドする

カスタムフロー参照

タスク	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 プロップの概要	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

アピアランスパターン

<SignIn
  appearance={{
    variables: {
      colorPrimary: '#0000ff',
      borderRadius: '0.5rem',
    },
    options: {
      logoImageUrl: '/logo.png',
      socialButtonsVariant: 'iconButton',
    },
  }}
/>

Core 2 のみ (現在の SDK を使用している場合はスキップ): options プロパティは layout という名前でした。options の代わりに layout: { logoImageUrl: '...', socialButtonsVariant: '...' } を使用してください。

variables (色、タイポグラフィ、ボーダー)

プロパティ	説明
colorPrimary	全体のプライマリカラー
colorBackground	背景色
borderRadius	ボーダー半径 (デフォルト: 0.375rem)

不透明度の変更: colorRing と colorModalBackdrop は現在フル不透明度でレンダリングされます。透明度が必要な場合は明示的な rgba() 値を使用してください。

Core 2 のみ (現在の SDK を使用している場合はスキップ): colorRing と colorModalBackdrop はデフォルトで 15% の不透明度でレンダリングされていました。

options (構造、ロゴ、ソーシャルボタン)

プロパティ	説明
logoImageUrl	カスタムロゴへの URL
socialButtonsVariant	'blockButton' | 'iconButton' | 'auto'
socialButtonsPlacement	'top' | 'bottom'
showOptionalFields	オプショナルフィールドを表示 (デフォルト: false)

Core 2 のみ (現在の SDK を使用している場合はスキップ): このプロパティは layout という名前です。また、showOptionalFields はデフォルトで true でした。

テーマ

@clerk/ui からテーマをインストールしてください:

npm install @clerk/ui

import { dark } from '@clerk/ui/themes'

<ClerkProvider appearance={{ theme: dark }} />

Core 2 のみ (現在の 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 のみ (現在の SDK を使用している場合はスキップ): @clerk/themes と @clerk/themes/shadcn.css からインポートしてください:

import { shadcn } from "@clerk/themes";

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

ワークフロー

1. カスタマイズのニーズを特定 (カスタムフロー、またはアピアランス)
2. カスタムフローの場合: SDK バージョンを確認 → 適切な core-2/ または core-3/ 参照を読む
3. アピアランスの場合: 上のテーブルから適切なドキュメンテーションを WebFetch
4. Clerk コンポーネントに appearance プロップを適用、または フックでカスタムフローを構築

よくある落とし穴

問題	解決方法
色が適用されない	primaryColor ではなく colorPrimary を使用してください
ロゴが表示されない	logoImageUrl を options: {} 内に配置してください (Core 2 では layout: {})
ソーシャルボタンが間違っている	options で socialButtonsVariant: 'iconButton' を追加してください (Core 2 では layout 内)
スタイリングが機能しない	直接 CSS ではなく appearance プロップを使用してください (bring-your-own-css を除く)
フックが異なる形状を返す	SDK バージョンを確認してください — Core 2 と現在のバージョンは useSignIn/useSignUp API が完全に異なります