clerk-custom-ui

カスタム UI

前提条件：アプリが ClerkProvider でラップされていることを確認してください。clerk-setup スキルを参照してください。

バージョン：SDK のバージョンは package.json で確認してください。バージョン一覧は clerk スキルを参照してください。使用するカスタムフローのリファレンスは、このバージョンに基づいて選びます。

このスキルでは、次の 2 つの領域について説明します。

1. カスタム認証フロー — フックを使って独自のサインイン／サインアップ UI を構築する
2. 外観のカスタマイズ — 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 と現在の SDK のどちらでも使用できます。

コンポーネントのカスタマイズオプション

作業	ドキュメント
Appearance プロパティの概要	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview
オプション（構造、ロゴ、ボタン）	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/options
テーマ（組み込みのダーク／ライト）	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

Appearance のパターン

<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 は、不透明度 100% で表示されるようになりました。透過が必要な場合は、明示的に rgba() の値を指定してください。

Core 2 のみ（現在の SDK ではスキップしてください）：colorRing と colorModalBackdrop は、デフォルトで不透明度 15% で表示されていました。

options（構造、ロゴ、ソーシャルボタン）

プロパティ	説明
logoImageUrl	カスタムロゴの URL
socialButtonsVariant	'blockButton' | 'iconButton' | 'auto'
socialButtonsPlacement	'top' | 'bottom'
showOptionalFields	オプションのフィールドを表示します（デフォルト：false）

Core 2 のみ（現在の SDK ではスキップしてください）：このプロパティの名前は options ではなく 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 テーマ

IMPORTANT: プロジェクトに 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 がまったく異なります

関連項目

• clerk-setup - Clerk の初期インストール
• clerk-nextjs-patterns - Next.js のパターン
• clerk-orgs - B2B 組織