ToggleGroup
여러 개의 Toggle을 하나의 그룹으로 제공하는 입력 컴포넌트
개요
ToggleGroup은 base-ui의 ToggleGroup Primitive를 기반으로 구축된 그룹 토글 컴포넌트입니다. 여러 토글 버튼을 하나의 그룹으로 묶어 다중 선택을 지원하며, 수평/수직 배치와 spacing 옵션을 제공합니다.
주요 특징
- ✅ 컴파운드 컴포넌트: ToggleGroup + ToggleGroupItem 구성
- ✅ 다중 선택: 그룹 내 여러 Toggle을 동시에 활성화
- ✅ 정렬 방향: 수평(horizontal) / 수직(vertical) 배치
- ✅ Spacing: 항목 간 간격 조절 (0이면 붙은 형태)
- ✅ Radius: xs, sm, md, lg, xl 5단계 둥근 모서리
- ✅ 읽기 전용: readOnly 상태에서 상태 전환 방지
- ✅ 접근성: base-ui 기반
aria-pressed자동 적용 - ✅ 디자인 토큰: 테마 커스터마이징 지원
사용 예시
기본 상태
여러 Toggle을 하나의 그룹으로 제공합니다.
Preview
선택 상태 표시
각 Toggle의 활성화(On) 상태를 시각적으로 표시합니다. defaultValue로 초기 선택 항목을 지정합니다.
Preview
다중 선택
그룹 내 여러 Toggle을 동시에 활성화할 수 있습니다. base-ui ToggleGroup은 기본적으로 다중 선택을 지원합니다.
Preview
정렬 방향
Toggle 항목을 가로 또는 세로 방향으로 배치할 수 있습니다.
Preview
수평 (기본)
수직
Default 값 설정
defaultValue로 초기 선택 값을 지정합니다. 배열 형태로 여러 항목을 기본 선택할 수 있습니다.
Preview
Variant와 Size
Toggle의 variant와 size를 그룹 레벨에서 일괄 지정합니다.
Preview
Default variant
Outline variant
Size sm
Size lg
Spacing
spacing prop으로 항목 간 간격을 조절합니다. 기본값 0은 항목이 붙어있는 형태입니다.
Preview
spacing=0 (기본, 붙은 형태)
spacing=1
비활성 상태
Preview
API Reference
ToggleGroup Props
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "default" | "outline" | "default" | 시각적 스타일 |
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 그룹 내 Toggle 크기 |
radius | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 그룹 둥근 모서리 |
spacing | number | 0 | 항목 간 간격 (0이면 붙은 형태) |
orientation | "horizontal" | "vertical" | "horizontal" | 항목 배치 방향 |
value | string[] | - | 선택된 값 (제어 모드) |
defaultValue | string[] | [] | 초기 선택 값 (비제어 모드) |
disabled | boolean | - | 전체 비활성화 |
className | string | - | 추가 CSS 클래스 |
ToggleGroup Events
| Event | Type | Description |
|---|---|---|
onValueChange | (value: string[]) => void | 값 변경 시 호출 |
ToggleGroupItem Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | - | 항목 값 (필수) |
disabled | boolean | - | 개별 비활성화 |
className | string | - | 추가 CSS 클래스 |
children | React.ReactNode | - | 내용 |
기본 사용법
import { ToggleGroup, ToggleGroupItem } from "@vortex/ui-foundation"
<ToggleGroup defaultValue={["bold"]}>
<ToggleGroupItem value="bold" aria-label="굵게">
<Bold className="size-4" />
</ToggleGroupItem>
<ToggleGroupItem value="italic" aria-label="기울임">
<Italic className="size-4" />
</ToggleGroupItem>
</ToggleGroup>접근성
ARIA 속성
- base-ui가 각 ToggleGroupItem에
aria-pressed자동 설정 - 포커스 링 자동 적용 (
focus-visible)
키보드 네비게이션
- Tab: 그룹으로 포커스 이동
- Space / Enter: 토글 전환
- ← → ↑ ↓: 항목 간 이동
권장 사항
- ✅ 아이콘만 사용 시
aria-label반드시 추가 - ✅ 시각적으로 눌림 상태를 명확히 구분
- ❌ 단일 선택이 필요한 경우 RadioGroup 사용 권장
관련 컴포넌트
Last updated on