はい、承知いたしました。
「shadcn/uiの基本的な使い方とカスタマイズ方法」についての詳細な説明を含む、約5000語の記事を作成します。以下、記事の内容です。

【コピペでOK】shadcn/uiの基本的な使い方とカスタマイズ方法を徹底解説

モダンフロントエンド開発の世界では、UIコンポーネントライブラリは必要不可欠なツールです。MUI (Material-UI)、Chakra UI、Ant Designなど、数多くの優れたライブラリが存在し、私たちの開発を支えてきました。しかし、近年、これらとは一線を画す新しいアプローチを提唱するツールが登場し、世界中のReact開発者から絶大な支持を集めています。それが「shadcn/ui」です。

shadcn/uiは、従来のコンポーネントライブラリとは根本的に思想が異なります。それは「ライブラリではない」と公言しており、コンポーネントをnpmパッケージとしてインストールするのではなく、必要なコンポーネントのコードを直接あなたのプロジェクトにコピー＆ペーストするというユニークな仕組みを採用しています。

このアプローチにより、開発者はコンポーネントの完全な所有権を持つことができ、無限のカスタマイズ性を手に入れることができます。ブラックボックス化されたコンポーネントの挙動に悩まされることなく、プロジェクトの要件に合わせて自由にコードを改変できるのです。

この記事では、そんな革新的なツールであるshadcn/uiの魅力を余すところなくお伝えします。環境構築から基本的な使い方、そしてshadcn/uiの真骨頂である詳細なカスタマイズ方法、さらには実践的な応用例まで、この1記事でマスターできるように網羅的に解説します。

「コピペでOK」なコードスニペットを豊富に用意しましたので、ぜひ実際に手を動かしながら、次世代のUI開発体験を味わってみてください。

第1章: shadcn/uiの概要と特徴

まず、shadcn/uiがどのようなもので、なぜこれほどまでに注目されているのかを深く理解しましょう。

1. shadcn/uiとは？

shadcn/uiは、一言で言えば「再利用可能なコンポーネントのコレクション」です。しかし、重要なのはその提供方法です。

従来のライブラリでは npm install @mui/material のようにパッケージをインストールし、import { Button } from '@mui/material'; のようにnode_modules内のコードをインポートして使います。この場合、コンポーネントの内部実装はブラックボックスであり、カスタマイズは提供されたpropsやテーマ機能の範囲内に限られます。

一方、shadcn/uiはCLI（コマンドラインインターフェース）を提供します。
npx shadcn-ui@latest add button
このコマンドを実行すると、Buttonコンポーネントのソースコード（.tsxファイル）が、あなたのプロジェクト内の指定したディレクトリ（例: src/components/ui/button.tsx）に直接生成されます。

つまり、あなたはコンポーネントの「利用者」ではなく、「所有者」になるのです。

このアーキテクチャは、2つの強力な技術スタックの上に成り立っています。

• Radix Primitives: アクセシビリティに優れたヘッドレスUIコンポーネントライブラリです。キーボード操作、フォーカス管理、WAI-ARIA属性など、複雑で面倒なアクセシビリティ対応を裏側で完璧に処理してくれます。shadcn/uiは、このRadixをベースにロジックを構築しています。
• Tailwind CSS: ユーティリティファーストのCSSフレームワークです。shadcn/uiのコンポーネントはすべてTailwind CSSのユーティリティクラスでスタイリングされており、直感的かつ柔軟なデザイン調整が可能です。

shadcn/uiは、Radixの堅牢なロジックとアクセシビリティに、Tailwind CSSの無限の表現力を組み合わせた、美しく設計されたコンポーネント群を、あなたの手元に直接届けてくれるツールなのです。

2. shadcn/uiのメリット

shadcn/uiが提供する価値は多岐にわたります。

• 完全な所有権と無限のカスタマイズ性: コードが自分のプロジェクト内にあるため、propsを追加したり、内部ロジックを変更したり、アニメーションを加えたりと、文字通り何でもできます。外部ライブラリの仕様に縛られることはありません。
• 高いデザイン自由度: Tailwind CSSベースであるため、tailwind.config.jsで定義したデザイントークン（色、スペーシング、フォントなど）がそのまま活かされます。プロジェクトのデザインシステムと完全に統合することが容易です。
• 最高のアクセシビリティ: Radix Primitivesをベースにしているため、提供されるコンポーネントは最初からアクセシビリティが考慮されています。これは、すべてのユーザーにとって使いやすいアプリケーションを構築する上で非常に重要です。
• バンドルサイズの最適化: 必要なコンポーネントだけをプロジェクトに追加するため、未使用のコンポーネントコードが最終的なバンドルに含まれることはありません。アプリケーションを軽量に保つことができます。
• 依存関係からの解放: node_modulesに巨大なUIライブラリを追加しないため、依存関係の競合や、ライブラリの破壊的変更に追従するコストから解放されます。
• 学習教材として: よく設計されたReactコンポーネントの生コードに触れることができるため、ReactやTypeScript、アクセシビリティのベストプラクティスを学ぶための絶好の教材にもなります。

3. 従来のコンポーネントライブラリとの比較

この比較からも、shadcn/uiがいかに開発者にコントロール権を与える設計思想であるかがわかります。

第2章: 環境構築と導入

それでは、実際にshadcn/uiをプロジェクトに導入してみましょう。ここでは、最も一般的で相性の良いNext.js (App Router)をベースに解説します。

1. 前提条件

• Node.js (v18.17.0以降を推奨)
• npm, yarn, pnpmなどのパッケージマネージャ
• React / Next.js の基本的な知識

2. Next.jsプロジェクトへの導入手順

Step 1: Next.jsプロジェクトの作成

まだプロジェクトがない場合は、以下のコマンドで新しいNext.jsプロジェクトを作成します。TypeScriptの使用を強く推奨します。

bash
npx create-next-app@latest my-shadcn-app
ウィザードでは、TypeScript, Tailwind CSS, App Router を選択してください。

Step 2: shadcn/uiの初期化

作成したプロジェクトのディレクトリに移動し、initコマンドを実行します。

bash
cd my-shadcn-app
npx shadcn-ui@latest init

このコマンドを実行すると、対話形式でいくつかの質問をされます。これらはプロジェクトの構成をshadcn/uiに伝えるための重要な設定です。

text
Would you like to use TypeScript (recommended)? › yes
Which style would you like to use? › Default
Which color would you like to use as base color? › Slate
Where is your global CSS file? › app/globals.css
Do you want to use CSS variables for colors? › yes
Where is your tailwind.config.js located? › tailwind.config.js
Configure import alias for components: › @/components
Configure import alias for utils: › @/lib/utils
Are you using React Server Components? › yes
Write configuration to components.json. Proceed? › yes

各質問の意味を詳しく見ていきましょう。

• Use TypeScript?: yesを選択。shadcn/uiはTypeScriptと非常に相性が良いです。
• Which style?: DefaultとNew Yorkの2つのスタイルプリセットから選べます。Defaultはよりミニマル、New Yorkは少し装飾的なスタイルです。後から変更も可能なので、まずはDefaultで始めましょう。
• Base color?: アプリケーションの基本となるテーマカラーを選びます。ここで選んだ色（例: Slate）を元に、様々な階調のカラーパレットがCSS変数として生成されます。
• Global CSS file?: Tailwind CSSのディレクティブ（@tailwind base;など）や、テーマ全体のCSS変数が書き込まれるグローバルなCSSファイルの場所を指定します。Next.js App Routerのデフォルトは app/globals.css です。
• Use CSS variables for colors?: yesを強く推奨します。これにより、テーマカラーやダークモードの切り替えが非常に簡単になります。
• tailwind.config.js location?: Tailwind CSSの設定ファイルの場所です。通常はプロジェクトルートにあります。
• Import alias for components/utils: コンポーネントやユーティリティ関数をインポートする際のエイリアス（別名）を設定します。@/componentsのように設定すると、import { Button } from '@/components/ui/button'のように階層を意識せずスッキリと記述できます。tsconfig.json（またはjsconfig.json）にも対応する設定が自動で追加されます。
• React Server Components?: Next.js App Routerを使っている場合はyesを選択します。

すべての質問に答えると、設定がcomponents.jsonというファイルに保存され、必要な設定ファイルが自動で変更・作成されます。

Step 3: initコマンドによる変更内容の確認

initコマンドは、あなたのプロジェクトにいくつかの重要な変更を加えます。

1. tailwind.config.ts (または .js):

   • tailwindcss-animateプラグインが追加されます。
   • shadcn/uiのテーマ設定（色、角丸、キーフレームアニメーションなど）がtheme.extend内に追加されます。

2. app/globals.css:

   • ファイルの先頭に、選択したベースカラーに基づいた大量のCSS変数が追加されます。これらがサイト全体のデザイントークンとなります。ダークモード用の変数も含まれています。

   “`css
   / 例: globals.css に追加される内容 /
   @tailwind base;
   @tailwind components;
   @tailwind utilities;

   @layer base {
   :root {
   –background: 0 0% 100%;
   –foreground: 222.2 84% 4.9%;
   / … 大量のCSS変数が続く … /
   –radius: 0.5rem;
   }

   .dark {
   –background: 222.2 84% 4.9%;
   –foreground: 210 40% 98%;
   / … ダークモード用の変数が続く … /
   }
   }
   “`

3. @/lib/utils.ts:

   • clsxとtailwind-mergeという2つの便利なライブラリを組み合わせたcnというヘルパー関数が作成されます。これは、コンポーネントに渡されるclassNameを安全にマージするためのユーティリティです。例えば、cn("p-2", "p-4")はp-4だけを適用し、クラス名の衝突を解決してくれます。

4. components.json:

   • initコマンドで答えた設定内容が保存されるファイルです。CLIはこのファイルを見て、コンポーネントをどこに、どのように追加するかを判断します。

これで、shadcn/uiを使う準備が整いました。

第3章: コンポーネントの追加と基本的な使い方

準備ができたので、実際にコンポーネントをプロジェクトに追加して使ってみましょう。

1. CLIを使ったコンポーネントの追加

shadcn/uiのコンポーネントは、addコマンドで個別に追加します。まずは最も基本的なButtonコンポーネントを追加してみましょう。

bash
npx shadcn-ui@latest add button

コマンドを実行すると、init時に設定したコンポーネントのパス（例: @/components）配下に、ui/button.tsxというファイルが作成されます。

- components/
- ui/
- button.tsx <-- これが生成される
- lib/
- ...

このbutton.tsxが、あなたが所有するButtonコンポーネントのソースコードです。

同様に、他のコンポーネントも追加できます。複数同時に追加することも可能です。

bash
npx shadcn-ui@latest add card input label dialog

2. Buttonコンポーネントを使ってみる

app/page.tsxを開き、追加したButtonコンポーネントを使ってみましょう。

app/page.tsx
“`tsx
import { Button } from “@/components/ui/button”;

export default function Home() {
return (

  {/* 基本的な使い方 */}
  <Button>Default Button</Button>

  {/* variant props で見た目を変更 */}
  <div className="flex gap-2">
    <Button variant="destructive">Destructive</Button>
    <Button variant="outline">Outline</Button>
    <Button variant="secondary">Secondary</Button>
    <Button variant="ghost">Ghost</Button>
    <Button variant="link">Link</Button>
  </div>

  {/* size props でサイズを変更 */}
  <div className="flex gap-2 items-center">
    <Button size="lg">Large</Button>
    <Button size="default">Default</Button>
    <Button size="sm">Small</Button>
    <Button size="icon">
      {/* Heroicons などのアイコンライブラリと組み合わせる */}
      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M11 13H5v-2h6V5h2v6h6v2h-6v6h-2v-6Z"/></svg>
    </Button>
  </div>

  {/* className props でスタイルを上書き・追加 */}
  <Button className="bg-gradient-to-r from-indigo-500 via-purple-500 to-pink-500 text-white">
    Custom Gradient
  </Button>

</main>

  {/* カードに影とボーダーを追加 */}
  <Card className="mt-4 shadow-xl border-2 border-fuchsia-500">
    <CardHeader>
      <CardTitle>Custom Card</CardTitle>
    </CardHeader>
    <CardContent>
      <p>This card has custom styles applied via className.</p>
    </CardContent>
  </Card>
</div>

/* 例1: サイト全体の角丸を大きくする */
--radius: 1rem; /* 0.5remから変更 */

          {JSON.stringify(values, null, 2)}