ButtonGroup
ButtonGroupは、関連するボタンを視覚的にグループ化するコンテナコンポーネントです。ツールバー、フィルター、アクショングループなど、複数の選択肢を1つのユニットとして提示する場合に使用します。
ButtonGroupにvariant、sizeを指定すると、子Button・IconButtonに自動継承されます。個別にオーバーライドも可能です。
Playground
<ButtonGroup variant="outline">
<Button>Copy</Button>
<Button>Cut</Button>
<Button>Paste</Button>
</ButtonGroup>Variants
Sizes
ButtonGroupはButtonのサイズをContextで継承します。以下はButtonと同じサイズ規則です。
xssmmddefaultlg| Size | 高さ | 横パディング | Gap | アイコン | フォント | プレビュー |
|---|---|---|---|---|---|---|
xs | 28px | 10px | 4px | 14px | 12px | |
sm | 32px | 12px | 8px | 14px | 13px | |
md | 36px | 14px | 8px | 16px | 14px | |
default | 40px | 16px | 8px | 16px | 14px | |
lg | 48px | 24px | 8px | 16px | 16px |
タッチターゲット: WCAG 2.5.8基準では最小24pxのタッチ領域が必要です。最小のxs（28px）でもWCAG基準を満たしています。
Features
Variant Combinations
// Edit Actions (outline) - Click to execute immediately
<ButtonGroup variant="outline" size="sm">
<Button leftIcon={<Copy />}>Copy</Button>
<Button leftIcon={<Scissors />}>Cut</Button>
<Button leftIcon={<Clipboard />}>Paste</Button>
</ButtonGroup>
// Undo/Redo Actions (outline) - History operations
<ButtonGroup variant="outline" size="sm">
<IconButton aria-label="Undo"><Undo /></IconButton>
<IconButton aria-label="Redo"><Redo /></IconButton>
</ButtonGroup>
// Zoom Controls (outline) - Zoom in/out actions
<ButtonGroup variant="outline" size="sm">
<IconButton aria-label="Zoom out"><ZoomOut /></IconButton>
<IconButton aria-label="Reset"><RotateCcw /></IconButton>
<IconButton aria-label="Zoom in"><ZoomIn /></IconButton>
</ButtonGroup>
Orientation
API
Props
variantundefined"outline" | "ghost"子Buttonのバリアント（Contextで継承）
sizeundefined"xs" | "sm" | "md" | "default" | "lg"子Buttonのサイズ（Contextで継承）
radiusundefined"none" | "sm" | "base" | "default" | "lg" | "xl" | "2xl" | "3xl" | "full"子Buttonの角丸（Contextで継承）
fontWeightundefined"normal" | "semibold"子Buttonのフォント太さ（Contextで継承）
disabledundefinedboolean全ボタンを無効化（Contextで継承）
orientation"horizontal""horizontal" | "vertical"ボタンの配置方向
attachedtruebooleanボタン同士を結合して表示するかどうか
| Name | Type | Default | Description |
|---|---|---|---|
variant | "outline" | "ghost" | undefined | 子Buttonのバリアント（Contextで継承） |
size | "xs" | "sm" | "md" | "default" | "lg" | undefined | 子Buttonのサイズ（Contextで継承） |
radius | "none" | "sm" | "base" | "default" | "lg" | "xl" | "2xl" | "3xl" | "full" | undefined | 子Buttonの角丸（Contextで継承） |
fontWeight | "normal" | "semibold" | undefined | 子Buttonのフォント太さ（Contextで継承） |
disabled | boolean | undefined | 全ボタンを無効化（Contextで継承） |
orientation | "horizontal" | "vertical" | "horizontal" | ボタンの配置方向 |
attached | boolean | true | ボタン同士を結合して表示するかどうか |
Customization
すべてのボタンはデザインシステムのスペーシングルールに基づいたデフォルト値を使用します。グループのclassNameで全ボタンを一括カスタマイズできます。
横パディングの変更
className="[&>button]:px-10"ボタン幅の均等化
className="inline-grid grid-flow-col auto-cols-fr"Tip：デフォルト値はコンポーネントの一貫性を保つよう設計されています。UI実装上カスタマイズが必要な場合にご活用ください。
Anatomy
horizontal · verticalgroupBest Practices
推奨
- ✓関連するアクションのみをグループ化
- ✓ButtonGroupにvariant/sizeを指定（子に継承）
- ✓3〜5個のボタンを目安に
- ✓アイコンのみのグループには aria-label を設定
<ButtonGroup variant="outline" size="sm">
<Button>A</Button>
<Button>B</Button>
</ButtonGroup>避けるべき
- ✗異なるサイズのボタンを混在させない
- ✗無関係なアクションをグループ化しない
- ✗6個以上のボタンを詰め込まない
- ✗destructiveボタンを他と混在させない
Accessibility
キーボード操作
ARIA属性
- role="group" 自動付与
- セマンティックなグルーピング
- aria-label 推奨
- フォーカス可視化サポート
ButtonGroup vs ToggleGroup
似たような見た目ですが、用途と動作が異なります。適切なコンポーネントを選択してください。
用途
ButtonGroup: アクションボタンのグループ化
ToggleGroup: オン/オフ状態の管理
状態管理
ButtonGroup: 手動 (selected prop)
ToggleGroup: 自動 (Radix管理)
選択モード
ButtonGroup: 手動制御のみ
ToggleGroup: single / multiple
value管理
ButtonGroup: なし
ToggleGroup: value / onValueChange
ユースケース
ButtonGroup: ツールバー、アクショングループ
ToggleGroup: テキスト配置、フォーマット
| 特徴 | ButtonGroup | ToggleGroup |
|---|---|---|
| 用途 | アクションボタンのグループ化 | オン/オフ状態の管理 |
| 状態管理 | 手動 (selected prop) | 自動 (Radix管理) |
| 選択モード | 手動制御のみ | single / multiple |
| value管理 | なし | value / onValueChange |
| ユースケース | ツールバー、アクショングループ | テキスト配置、フォーマット |
選択の目安: 選択状態を自動で管理したい場合は ToggleGroup を使用してください。クリック時に特定のアクション（API呼び出し等）を実行する場合は ButtonGroup が適切です。