Skip to Content
ComponentsIcignalCheckbox

Checkbox

레이블을 포함한 체크박스 입력 컴포넌트

개요

iCignal Checkbox는 Foundation Checkbox를 래핑하여 레이블 기능을 추가한 컴포넌트입니다.

주요 특징

  • ✅ 레이블 통합: 체크박스 우측에 레이블 자동 배치
  • ✅ 다양한 크기: xs, sm, md, lg, xl 5단계 크기 지원
  • ✅ 읽기 전용: readOnly 상태에서 조회만 가능
  • ✅ 오류 상태: aria-invalid를 통한 시각적 오류 표시
  • ✅ 접근성: ARIA 속성 자동 적용
  • ✅ 디자인 토큰: 테마 커스터마이징 지원

Sizes

사용 예시

기본 상태

단일 항목의 선택 또는 해제를 위한 입력 요소입니다.

체크 상태 표시

선택 시 Checked 상태를 시각적으로 표시합니다.

읽기 전용 상태

읽기 전용 상태에서는 조회만 가능하며 선택 및 변경이 제한됩니다.

오류 상태 표시

오류 발생 시 aria-invalid 속성으로 시각적 피드백을 제공합니다.

레이블 제공

체크박스에 레이블을 제공하며, 레이블은 체크박스 우측에 배치됩니다. 레이블 클릭 시에도 토글이 동작합니다.

레이블 없이 사용

레이블 없이 체크박스만 단독으로 사용할 수도 있습니다.

API Reference

Props

PropTypeDefaultDescription
labelReactNode-체크박스 우측 레이블
size"xs" | "sm" | "md" | "lg" | "xl""md"체크박스 크기
checkedboolean-체크 상태 (제어 모드)
defaultCheckedboolean-초기 체크 상태 (비제어 모드)
indeterminateboolean-부분 선택 상태
disabledboolean-비활성화 여부
readOnlyboolean-읽기 전용 여부
valuestring-폼 제출 시 전달되는 값
namestring-폼 필드 이름
classNamestring-추가 CSS 클래스

Events

EventTypeDescription
onCheckedChange(checked: boolean) => void체크 상태 변경 콜백

기본 사용법

import { Checkbox } from "@vortex/ui-icignal"
 
<Checkbox label="동의합니다" />
<Checkbox label="선택됨" defaultChecked />
<Checkbox label="읽기 전용" readOnly defaultChecked />
<Checkbox label="비활성" disabled />

접근성

ARIA 속성

Base UI Checkbox가 자동으로 제공합니다:

// role="checkbox" 자동 적용
// aria-checked="true" | "false" | "mixed" 자동 적용
// aria-disabled 자동 적용
<Checkbox label="이용약관 동의" />

권장 사항

  • ✅ label prop을 통해 레이블을 제공
  • ✅ 레이블 없이 사용할 경우 aria-label 추가
  • ✅ 에러 상태 시 aria-invalid 속성 추가
  • ❌ 라벨 없이 단독 사용 지양

관련 컴포넌트

Last updated on
BoxHelperCheckboxGroup