Storybook Args/ArgTypes 速見表:Controls/Docs/Autodocs を一気に整える

Storybook で UI コンポーネントを開発する際、Args と ArgTypes の設定で悩んだ経験はありませんか?Controls パネルの表示が思い通りにならなかったり、Autodocs の説明が不十分だったり。この記事では、Args と ArgTypes を正しく設定して、Controls・Docs・Autodocs を一気に整える方法をご紹介します。早見表を見ながら、すぐに実践できる内容になっていますよ。
Args/ArgTypes 早見表
以下の表は、よく使う ArgTypes の設定パターンを一覧にまとものです。この表を参考にしながら、コンポーネントに合わせて設定を進められます。
| # | プロパティ | 型 | 説明 | Controls への影響 | Docs への影響 | 
|---|---|---|---|---|---|
| 1 | control | object/false | Controls パネルの UI タイプを指定 | 表示される UI を変更 | - | 
| 2 | description | string | プロパティの説明文 | - | Docs テーブルに表示 | 
| 3 | table.type.summary | string | 型の要約表示 | - | Docs の型列に表示 | 
| 4 | table.defaultValue.summary | string | デフォルト値の表示 | - | Docs のデフォルト列に表示 | 
| 5 | options | array | select/radio で選択可能な値 | 選択肢を表示 | - | 
| 6 | if | object | 条件付き表示の設定 | 条件に応じて表示/非表示 | - | 
| 7 | table.category | string | プロパティのカテゴリ分類 | - | Docs でグループ化 | 
| 8 | table.subcategory | string | プロパティのサブカテゴリ | - | Docs でサブグループ化 | 
| 9 | mapping | object | 値とコンポーネントのマッピング | - | 複雑な値の表示に対応 | 
| 10 | control.labels | object | select/radio の選択肢ラベル | ラベルを変更 | - | 
背景
Storybook は、UI コンポーネントを独立した環境で開発・テストできる強力なツールです。中でも Args と ArgTypes は、コンポーネントの Props を動的に操作したり、ドキュメントを自動生成したりする核心的な機能なんですね。
Args と ArgTypes の役割
Args はコンポーネントに渡される実際の値(Props)を表し、ArgTypes はその値の「型情報」「説明」「Controls の表示方法」などのメタデータを定義します。この 2 つを適切に設定することで、以下のような恩恵が得られるんです。
- Controls パネル:UI 上で Props を動的に変更できる
- Docs タブ:自動生成されたドキュメントに詳細な説明が表示される
- Autodocs:TypeScript の型情報から自動的にドキュメントを生成できる
次の図は、Args と ArgTypes がどのように Storybook の各機能に影響するかを示しています。
mermaidflowchart TB
  component["コンポーネント<br/>(Props を受け取る)"]
  args["Args<br/>(実際の値)"]
  argTypes["ArgTypes<br/>(メタデータ)"]
  controls["Controls パネル<br/>(動的操作)"]
  docs["Docs タブ<br/>(ドキュメント)"]
  autodocs["Autodocs<br/>(自動生成)"]
  component --> args
  component --> argTypes
  args --> controls
  argTypes --> controls
  argTypes --> docs
  argTypes --> autodocs
  controls -.->|値を変更| args
この図からわかるように、ArgTypes はすべての表示機能に影響を与える中心的な存在です。
課題
Args と ArgTypes の設定で、開発者がよく直面する課題があります。それは「設定項目が多すぎて、何をどう設定すればいいかわからない」という問題です。
よくある困りごと
以下のような悩みを抱えている方は多いのではないでしょうか。
- Controls パネルに不要なプロパティが表示されてしまう
- select や radio の選択肢が表示されない
- Docs タブの説明が空欄になってしまう
- デフォルト値が正しく表示されない
- TypeScript の型情報が Autodocs に反映されない
- プロパティをカテゴリ分けして整理したい
これらの問題は、ArgTypes の設定が不十分だったり、間違った方法で設定していたりすることが原因なんですね。特に、Controls と Docs の両方に影響する設定項目があるため、混乱しやすいのです。
次の図は、ArgTypes の設定不足がどのような問題を引き起こすかを示しています。
mermaidflowchart LR
  setup["ArgTypes 設定"]
  problem1["Controls に不要な<br/>項目が表示"]
  problem2["選択肢が表示<br/>されない"]
  problem3["Docs の説明が<br/>空欄"]
  problem4["デフォルト値が<br/>不正確"]
  setup -.->|control 未設定| problem1
  setup -.->|options 未設定| problem2
  setup -.->|description 未設定| problem3
  setup -.->|table.defaultValue 未設定| problem4
これらの課題を解決するには、各設定項目の役割を理解し、適切に設定する必要があります。
解決策
Args と ArgTypes を正しく設定すれば、Controls・Docs・Autodocs のすべてを一気に整えられます。ここでは、実践的な設定方法を段階的にご紹介しますね。
ArgTypes の基本構造
ArgTypes は Story ファイルの meta オブジェクトまたは個別の Story 内で定義できます。基本的な構造は以下の通りです。
typescriptimport type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    // ここに各プロパティの設定を記述
  },
};
export default meta;
ArgTypes には、プロパティ名をキーとして、各種設定を記述していきます。
Controls パネルの制御
Controls パネルに表示する UI は control プロパティで指定できます。不要なプロパティは control: false で非表示にしましょう。
typescriptargTypes: {
  // テキスト入力
  label: {
    control: 'text',
  },
  // 数値入力(範囲指定)
  size: {
    control: {
      type: 'range',
      min: 10,
      max: 100,
      step: 5,
    },
  },
  // 非表示にする
  onClick: {
    control: false,
  },
}
control の type には、text、number、boolean、select、radio、color、date など、多様な UI タイプが用意されています。
選択肢の設定
select や radio で選択肢を表示するには、options プロパティを使います。さらに、control.labels で表示ラベルをカスタマイズできますよ。
typescriptargTypes: {
  variant: {
    control: 'select',
    options: ['primary', 'secondary', 'tertiary'],
    description: 'ボタンの種類を選択します',
  },
  size: {
    control: 'radio',
    options: ['small', 'medium', 'large'],
    control: {
      type: 'radio',
      labels: {
        small: '小',
        medium: '中',
        large: '大',
      },
    },
  },
}
この設定により、Controls パネルで直感的に選択肢を操作できるようになります。
Docs タブの説明追加
Docs タブには、description と table プロパティを使って詳細な情報を追加できます。これにより、チームメンバーが理解しやすいドキュメントが自動生成されるんです。
typescriptargTypes: {
  variant: {
    description: 'ボタンのスタイルバリエーションを指定します。primary は主要アクション、secondary は補助アクション、tertiary は軽微なアクションに使用します。',
    table: {
      type: {
        summary: '"primary" | "secondary" | "tertiary"',
      },
      defaultValue: {
        summary: 'primary',
      },
    },
  },
}
table.type.summary で型情報を、table.defaultValue.summary でデフォルト値を明示的に記載します。
カテゴリ分類
プロパティが多い場合は、table.category と table.subcategory でグループ化すると見やすくなります。Docs タブでカテゴリごとに折りたたみ表示されるため、大規模なコンポーネントでも整理された状態を保てるんですね。
typescriptargTypes: {
  variant: {
    description: 'ボタンのスタイル',
    table: {
      category: 'Appearance',
    },
  },
  size: {
    description: 'ボタンのサイズ',
    table: {
      category: 'Appearance',
    },
  },
  onClick: {
    description: 'クリック時のイベントハンドラ',
    table: {
      category: 'Events',
    },
  },
  disabled: {
    description: '無効状態',
    table: {
      category: 'State',
    },
  },
}
カテゴリ分けにより、「見た目」「イベント」「状態」などの関心事ごとにプロパティを整理できます。
条件付き表示
特定の条件下でのみプロパティを表示したい場合は、if プロパティを使います。これにより、関連するプロパティだけを表示できるんです。
typescriptargTypes: {
  variant: {
    control: 'select',
    options: ['primary', 'secondary', 'outlined'],
  },
  outlineColor: {
    control: 'color',
    if: { arg: 'variant', eq: 'outlined' },
    description: 'アウトラインの色(variant が outlined の場合のみ有効)',
  },
}
この設定により、variant が outlined の場合のみ outlineColor が Controls パネルに表示されます。
具体例
実際のコンポーネントで Args と ArgTypes を設定する例を見ていきましょう。Button コンポーネントを題材に、段階的に設定を進めていきます。
Button コンポーネントの定義
まず、TypeScript で型定義された Button コンポーネントを用意します。
typescript// Button.tsx
export interface ButtonProps {
  /**
   * ボタンのラベル
   */
  label: string;
  /**
   * ボタンのスタイルバリエーション
   */
  variant?: 'primary' | 'secondary' | 'tertiary';
  /**
   * ボタンのサイズ
   */
  size?: 'small' | 'medium' | 'large';
  /**
   * 無効状態
   */
  disabled?: boolean;
  /**
   * クリック時のイベントハンドラ
   */
  onClick?: () => void;
}
この型定義には JSDoc コメントが含まれており、Autodocs でも活用できます。
typescriptexport const Button: React.FC<ButtonProps> = ({
  label,
  variant = 'primary',
  size = 'medium',
  disabled = false,
  onClick,
}) => {
  return (
    <button
      className={`btn btn-${variant} btn-${size}`}
      disabled={disabled}
      onClick={onClick}
    >
      {label}
    </button>
  );
};
シンプルな Button コンポーネントですが、複数のプロパティを持っているため、適切な設定が必要です。
Story ファイルの作成
次に、Story ファイルで ArgTypes を設定していきます。まずは基本的な meta 定義から。
typescript// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
};
export default meta;
type Story = StoryObj<typeof Button>;
tags: ['autodocs'] を指定することで、Autodocs が有効になります。
ArgTypes の詳細設定
ここからが本題です。ArgTypes に詳細な設定を追加していきましょう。
typescriptconst meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    label: {
      control: 'text',
      description: 'ボタンに表示するテキストラベルです。',
      table: {
        type: { summary: 'string' },
        category: 'Content',
      },
    },
  },
};
label は必須プロパティなので、テキスト入力として設定し、「Content」カテゴリに分類しました。
typescript    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'tertiary'],
      description: 'ボタンのスタイルバリエーションを選択します。primary は主要アクション、secondary は補助アクション、tertiary は軽微なアクションに使用してください。',
      table: {
        type: { summary: '"primary" | "secondary" | "tertiary"' },
        defaultValue: { summary: 'primary' },
        category: 'Appearance',
      },
    },
variant は選択式にし、各選択肢の用途も説明文に含めています。
typescript    size: {
      control: 'radio',
      options: ['small', 'medium', 'large'],
      description: 'ボタンのサイズを選択します。',
      table: {
        type: { summary: '"small" | "medium" | "large"' },
        defaultValue: { summary: 'medium' },
        category: 'Appearance',
      },
    },
size はラジオボタンで選択できるようにしました。
typescript    disabled: {
      control: 'boolean',
      description: 'true の場合、ボタンが無効化されクリックできなくなります。',
      table: {
        type: { summary: 'boolean' },
        defaultValue: { summary: 'false' },
        category: 'State',
      },
    },
disabled は boolean なので、トグルスイッチとして表示されます。
typescript    onClick: {
      control: false,
      description: 'ボタンがクリックされたときに実行される関数です。',
      table: {
        type: { summary: '() => void' },
        category: 'Events',
      },
    },
  },
};
onClick はイベントハンドラなので、Controls パネルでは非表示にしていますが、Docs には説明を残しています。
Default Story の作成
ArgTypes の設定が完了したら、デフォルトの Story を作成しましょう。
typescriptexport const Primary: Story = {
  args: {
    label: 'Button',
    variant: 'primary',
    size: 'medium',
    disabled: false,
  },
};
export const Secondary: Story = {
  args: {
    label: 'Button',
    variant: 'secondary',
    size: 'medium',
    disabled: false,
  },
};
各 Story には初期値として Args を設定します。これにより、Controls パネルで値を変更する起点となるんですね。
typescriptexport const Small: Story = {
  args: {
    label: 'Button',
    variant: 'primary',
    size: 'small',
  },
};
export const Large: Story = {
  args: {
    label: 'Button',
    variant: 'primary',
    size: 'large',
  },
};
export const Disabled: Story = {
  args: {
    label: 'Button',
    variant: 'primary',
    disabled: true,
  },
};
サイズや状態ごとに Story を用意することで、デザインシステムとしての一覧性も高まります。
動作確認のポイント
設定が完了したら、以下のポイントを確認してみてください。
- Controls パネル:label、variant、size、disabledが操作可能で、onClickは表示されていない
- Docs タブ:各プロパティの説明、型、デフォルト値が表示され、カテゴリごとに整理されている
- Autodocs:TypeScript の型情報と JSDoc コメントが反映されている
この流れで設定すれば、Controls・Docs・Autodocs のすべてが統一された情報を表示するようになります。
次の図は、完成した設定がどのように各機能に反映されるかを示しています。
mermaidflowchart TB
  argTypes["ArgTypes 設定<br/>(完全な設定)"]
  controls["Controls パネル"]
  docs["Docs タブ"]
  autodocs["Autodocs"]
  controlItems["・label: テキスト入力<br/>・variant: セレクト<br/>・size: ラジオ<br/>・disabled: トグル<br/>・onClick: 非表示"]
  docsItems["・説明文<br/>・型情報<br/>・デフォルト値<br/>・カテゴリ分類"]
  autodocsItems["・TypeScript 型<br/>・JSDoc コメント<br/>・自動生成"]
  argTypes --> controls
  argTypes --> docs
  argTypes --> autodocs
  controls --> controlItems
  docs --> docsItems
  autodocs --> autodocsItems
すべての設定が一箇所(ArgTypes)に集約されることで、メンテナンスも容易になるんです。
まとめ
Storybook の Args と ArgTypes を適切に設定することで、Controls パネル・Docs タブ・Autodocs のすべてを一気に整えられます。
設定のポイントをおさらいしましょう。
- control:Controls パネルの UI タイプを指定し、不要なものは falseで非表示
- description:Docs タブに表示される説明文を記述
- table.type.summary:型情報を明示的に記載
- table.defaultValue.summary:デフォルト値を記載
- options:select や radio の選択肢を配列で指定
- table.category:プロパティをカテゴリ分類して整理
- if:条件付きでプロパティを表示
これらの設定を活用すれば、チーム全体で一貫したコンポーネントドキュメントを維持できます。早見表を手元に置きながら、ぜひ実践してみてくださいね。
関連リンク
 article article- Storybook で“仕様が生きる”開発:ドキュメント駆動 UI の実践ロードマップ
 article article- Storybook リリース運用:Changesets とバージョン別ドキュメントの整備術
 article article- Storybook 情報設計の教科書:フォルダ/タイトル/ストーリー命名のベストプラクティス
 article article- Storybook Args/ArgTypes 速見表:Controls/Docs/Autodocs を一気に整える
 article article- Storybook を Monorepo に導入:Yarn Workspaces/Turborepo の最短レシピ
 article article- Storybook Builder 徹底比較:Vite vs Webpack vs Rspack の速度と互換性
 article article- MySQL ERROR 1449 対策:DEFINER 不明でビューやトリガーが壊れた時の復旧手順
 article article- Cursor で差分が崩れる/意図しない大量変更が入るときの復旧プレイブック
 article article- Motion(旧 Framer Motion)で exit が発火しない/遅延する問題の原因切り分けガイド
 article article- JavaScript 時刻の落とし穴大全:タイムゾーン/DST/うるう秒の実務対策
 article article- Cline が差分を誤適用する時:改行コード・Prettier・改フォーマット問題の解決
 article article- htmx で二重送信が起きる/起きない問題の完全対処:trigger と disable パターン
 blog blog- iPhone 17シリーズの発表!全モデルiPhone 16から進化したポイントを見やすく整理
 blog blog- Googleストアから訂正案内!Pixel 10ポイント有効期限「1年」表示は誤りだった
 blog blog- 【2025年8月】Googleストア「ストアポイント」は1年表記はミス?2年ルールとの整合性を検証
 blog blog- Googleストアの注文キャンセルはなぜ起きる?Pixel 10購入前に知るべき注意点
 blog blog- Pixcel 10シリーズの発表!全モデル Pixcel 9 から進化したポイントを見やすく整理
 blog blog- フロントエンドエンジニアの成長戦略:コーチングで最速スキルアップする方法
 review review- 今の自分に満足していますか?『持たざる者の逆襲 まだ何者でもない君へ』溝口勇児
 review review- ついに語られた業界の裏側!『フジテレビの正体』堀江貴文が描くテレビ局の本当の姿
 review review- 愛する勇気を持てば人生が変わる!『幸せになる勇気』岸見一郎・古賀史健のアドラー実践編で真の幸福を手に入れる
 review review- 週末を変えれば年収も変わる!『世界の一流は「休日」に何をしているのか』越川慎司の一流週末メソッド
 review review- 新しい自分に会いに行こう!『自分の変え方』村岡大樹の認知科学コーチングで人生リセット
 review review- 科学革命から AI 時代へ!『サピエンス全史 下巻』ユヴァル・ノア・ハラリが予見する人類の未来