Skip to Content
ComponentsIcignalToggleGroup

ToggleGroup

여러 토글 버튼을 그룹으로 관리하는 선택 컴포넌트

개요

ToggleGroup은 여러 토글 항목을 그룹으로 묶어 단일 또는 다중 선택을 지원하는 컴포넌트입니다. pill 스타일의 버튼과 커스텀 렌더링을 지원합니다.

주요 특징

  • ✅ 단일/다중 선택: multiple prop으로 전환
  • ✅ 배치 방향: 수평/수직 레이아웃 옵션
  • ✅ 커스텀 렌더링: renderItem으로 자유로운 UI
  • ✅ FormItem 통합: 레이블, 설명, 에러 메시지
  • ✅ 접근성: role=“group”, aria-checked 지원
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

Variants

선택 모드

배치 방향

Variant 설명

Variant설명사용 사례
multiple여러 항목 동시 선택메트릭 태그, 필터 선택
single하나만 선택 가능기간 선택, 뷰 모드 전환
horizontal가로 배치탭 대체, 필터 바
vertical세로 배치사이드바 옵션

States

사용 예시

예시 1: 분석 기간 필터

대시보드에서 데이터 조회 기간을 선택합니다.

예시 2: 메트릭 태그 선택

차트에 표시할 지표를 다중 선택합니다.

차트에 표시할 지표를 선택하세요

API Reference

Props

PropTypeDefaultDescription
itemsToggleGroupItem[]-토글 항목 배열 (필수)
valuestring[]-선택된 값 (제어)
defaultValuestring[][]기본 선택 값
onValueChange(value: string[]) => void-값 변경 핸들러
multiplebooleantrue다중 선택 모드
itemOrientation"horizontal" | "vertical""horizontal"항목 배치 방향
disabledbooleanfalse비활성화 여부
renderItem(item: ToggleGroupItem, pressed: boolean, toggle: () => void) => ReactNode-커스텀 렌더 함수
labelstring-필드 레이블
labelWidthstring | number-레이블 너비
requiredbooleanfalse필수 여부
orientation"horizontal" | "vertical""horizontal"레이블-필드 배치 방향
descriptionstring-설명 텍스트
errorstring-에러 메시지
classNamestring-추가 CSS 클래스

기본 사용법

import { ToggleGroup } from "@vortex/ui-icignal"
 
// 다중 선택
<ToggleGroup
  label="태그"
  items={[
    { value: "a", label: "옵션 A" },
    { value: "b", label: "옵션 B" },
  ]}
  defaultValue={["a"]}
/>
 
// 단일 선택
<ToggleGroup
  label="뷰 모드"
  multiple={false}
  items={[...]}
  defaultValue={["table"]}
/>

접근성

ARIA 속성

<ToggleGroup
  label="기간 선택"
  items={[
    { value: "7d", label: "7일" },
    { value: "30d", label: "30일" },
  ]}
/>

권장 사항

  • ✅ label을 제공하여 그룹 목적 전달
  • ✅ 키보드: Tab으로 이동, Space/Enter로 토글
  • ✅ role="group", aria-checked 자동 설정
  • ❌ 레이블 없이 단독 사용 지양

관련 컴포넌트

Last updated on
Toggle