Skip to Content
ComponentsIcignalCheckboxGroup

CheckboxGroup

여러 옵션을 동시에 선택할 수 있는 체크박스 그룹

개요

CheckboxGroup은 여러 체크박스를 하나의 그룹으로 관리하는 폼 컴포넌트입니다. FormItem을 통합하여 레이블, 설명, 에러 메시지를 지원합니다.

주요 특징

  • ✅ 다중 선택: 여러 항목 동시 선택 지원
  • ✅ 배치 방향: 수평/수직 레이아웃 옵션
  • ✅ 제어/비제어: value, defaultValue 모두 지원
  • ✅ FormItem 통합: 레이블, 설명, 에러 메시지
  • ✅ 접근성: WAI-ARIA Checkbox Group 패턴
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

Variants

배치 방향

Variant 설명

Variant설명사용 사례
horizontal항목을 가로로 배치옵션이 적을 때, 필터 UI
vertical항목을 세로로 배치옵션이 많을 때, 설정 폼

States

원하는 항목을 모두 선택하세요

사용 예시

예시 1: 데이터 필터 선택

분석 대시보드에서 여러 데이터 소스를 동시에 선택합니다.

분석에 포함할 소스를 선택하세요

예시 2: 차트 시리즈 선택

차트에 표시할 메트릭을 선택합니다.

API Reference

Props

PropTypeDefaultDescription
itemsCheckboxProps[][]체크박스 항목 배열
valuestring[]-선택된 값 (제어)
defaultValuestring[]-기본 선택 값
onValueChange(value: string[]) => void-값 변경 핸들러
itemOrientation"horizontal" | "vertical""horizontal"항목 배치 방향
disabledbooleanfalse비활성화 여부
labelstring-필드 레이블
labelWidthstring | number-레이블 너비
requiredbooleanfalse필수 여부
orientation"horizontal" | "vertical""horizontal"레이블-필드 배치 방향
descriptionstring-설명 텍스트
errorstring-에러 메시지
classNamestring-추가 CSS 클래스

기본 사용법

import { CheckboxGroup } from "@vortex/ui-icignal"
;<CheckboxGroup
  label="옵션 선택"
  items={[
    { value: "a", label: "옵션 A" },
    { value: "b", label: "옵션 B" },
  ]}
  defaultValue={["a"]}
/>

접근성

ARIA 속성

<CheckboxGroup
  label="필터"
  items={[
    { value: "a", label: "옵션 A" },
    { value: "b", label: "옵션 B" },
  ]}
/>

권장 사항

  • ✅ 항상 label을 제공하여 그룹의 목적을 명확히 전달
  • ✅ 에러 상태에서 error 메시지를 통해 구체적 안내
  • ✅ 키보드 네비게이션: Tab으로 이동, Space로 선택/해제
  • ❌ 레이블 없이 체크박스 그룹만 단독 사용 지양

관련 컴포넌트

Last updated on
iCignal ComponentsCombobox