ButtonGroup
ButtonGroup은 관련 버튼을 시각적으로 그룹화하는 컨테이너입니다. 툴바, 필터, 액션 그룹 등 여러 선택지를 하나의 유닛으로 묶을 때 사용합니다.
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)도 기준을 충족합니다.
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의 variant (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의 variant (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：기본값은 일관성을 유지하도록 설계되어 있습니다. 필요한 경우 커스터마이즈하세요.
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이 적합합니다.