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 の各機能に影響するかを示しています。

mermaidCopy codeflowchart 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 の設定不足がどのような問題を引き起こすかを示しています。

mermaidCopy codeflowchart 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 内で定義できます。基本的な構造は以下の通りです。

typescriptCopy codeimport 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 で非表示にしましょう。

typescriptCopy codeargTypes: {
  // テキスト入力
  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 で表示ラベルをカスタマイズできますよ。

typescriptCopy codeargTypes: {
  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 プロパティを使って詳細な情報を追加できます。これにより、チームメンバーが理解しやすいドキュメントが自動生成されるんです。

typescriptCopy codeargTypes: {
  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 タブでカテゴリごとに折りたたみ表示されるため、大規模なコンポーネントでも整理された状態を保てるんですね。

typescriptCopy codeargTypes: {
  variant: {
    description: 'ボタンのスタイル',
    table: {
      category: 'Appearance',
    },
  },

  size: {
    description: 'ボタンのサイズ',
    table: {
      category: 'Appearance',
    },
  },

  onClick: {
    description: 'クリック時のイベントハンドラ',
    table: {
      category: 'Events',
    },
  },

  disabled: {
    description: '無効状態',
    table: {
      category: 'State',
    },
  },
}

カテゴリ分けにより、「見た目」「イベント」「状態」などの関心事ごとにプロパティを整理できます。

条件付き表示

特定の条件下でのみプロパティを表示したい場合は、if プロパティを使います。これにより、関連するプロパティだけを表示できるんです。

typescriptCopy codeargTypes: {
  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 コンポーネントを用意します。

typescriptCopy code// Button.tsx
export interface ButtonProps {
  /**
   * ボタンのラベル
   */
  label: string;

  /**
   * ボタンのスタイルバリエーション
   */
  variant?: 'primary' | 'secondary' | 'tertiary';

  /**
   * ボタンのサイズ
   */
  size?: 'small' | 'medium' | 'large';

  /**
   * 無効状態
   */
  disabled?: boolean;

  /**
   * クリック時のイベントハンドラ
   */
  onClick?: () => void;
}

この型定義には JSDoc コメントが含まれており、Autodocs でも活用できます。

typescriptCopy codeexport 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 定義から。

typescriptCopy code// 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 に詳細な設定を追加していきましょう。

typescriptCopy codeconst meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],

  argTypes: {
    label: {
      control: 'text',
      description: 'ボタンに表示するテキストラベルです。',
      table: {
        type: { summary: 'string' },
        category: 'Content',
      },
    },
  },
};

label は必須プロパティなので、テキスト入力として設定し、「Content」カテゴリに分類しました。

typescriptCopy code    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'tertiary'],
      description: 'ボタンのスタイルバリエーションを選択します。primary は主要アクション、secondary は補助アクション、tertiary は軽微なアクションに使用してください。',
      table: {
        type: { summary: '"primary" | "secondary" | "tertiary"' },
        defaultValue: { summary: 'primary' },
        category: 'Appearance',
      },
    },

variant は選択式にし、各選択肢の用途も説明文に含めています。

typescriptCopy code    size: {
      control: 'radio',
      options: ['small', 'medium', 'large'],
      description: 'ボタンのサイズを選択します。',
      table: {
        type: { summary: '"small" | "medium" | "large"' },
        defaultValue: { summary: 'medium' },
        category: 'Appearance',
      },
    },

size はラジオボタンで選択できるようにしました。

typescriptCopy code    disabled: {
      control: 'boolean',
      description: 'true の場合、ボタンが無効化されクリックできなくなります。',
      table: {
        type: { summary: 'boolean' },
        defaultValue: { summary: 'false' },
        category: 'State',
      },
    },

disabled は boolean なので、トグルスイッチとして表示されます。

typescriptCopy code    onClick: {
      control: false,
      description: 'ボタンがクリックされたときに実行される関数です。',
      table: {
        type: { summary: '() => void' },
        category: 'Events',
      },
    },
  },
};

onClick はイベントハンドラなので、Controls パネルでは非表示にしていますが、Docs には説明を残しています。

Default Story の作成

ArgTypes の設定が完了したら、デフォルトの Story を作成しましょう。

typescriptCopy codeexport 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 パネルで値を変更する起点となるんですね。

typescriptCopy codeexport 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 のすべてが統一された情報を表示するようになります。

次の図は、完成した設定がどのように各機能に反映されるかを示しています。

mermaidCopy codeflowchart 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：条件付きでプロパティを表示

これらの設定を活用すれば、チーム全体で一貫したコンポーネントドキュメントを維持できます。早見表を手元に置きながら、ぜひ実践してみてくださいね。

関連リンク

• Storybook 公式ドキュメント - Args
• Storybook 公式ドキュメント - ArgTypes
• Storybook 公式ドキュメント - Controls
• Storybook 公式ドキュメント - Autodocs