Skip to Content

Checkbox

체크 가능한 옵션을 선택하는 폼 컴포넌트


개요

Checkbox 컴포넌트는 Base UI의 Checkbox를 기반으로 구축된 체크박스 컴포넌트입니다.

주요 특징

  • Base UI 기반: 접근성이 검증된 Headless UI
  • 다양한 크기: xs, sm, md, lg, xl 5단계 크기 지원
  • Indeterminate 상태: 부분 선택 상태 지원
  • 키보드 네비게이션: Space 키로 토글
  • 접근성: ARIA 속성 자동 적용
  • 디자인 토큰: 테마 커스터마이징 지원

Sizes

Checkbox는 5가지 크기를 지원합니다.

Extra Small
Small
Medium
Large
Extra Large

Size 설명

Size설명사용 사례
xs가장 작은 크기밀집된 목록, 테이블 내부
sm작은 크기컴팩트한 폼
md기본 크기일반적인 폼
lg큰 크기강조가 필요한 옵션
xl가장 큰 크기터치 최적화, 메인 동의항목

사용 예시

기본 사용

라벨과 함께 사용하는 기본 형태입니다.

Checked 상태

Disabled 상태

ReadOnly 상태

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

오류 상태

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

Indeterminate 상태

부분 선택 상태를 표시할 때 indeterminate prop을 사용합니다.

참고: Indeterminate는 시각적 상태만 나타내며, 체크박스 자체는 checked/unchecked 두 상태만 가집니다. Indeterminate → checked → unchecked 순환 전환은 자동으로 제공되지 않으며, onCheckedChange 콜백에서 상태를 직접 관리해야 합니다.

부분 선택됨

체크박스 그룹

여러 옵션을 그룹으로 묶어 표시합니다.

알림 설정

value 속성

value는 폼 제출 시 서버로 전달되는 값을 지정합니다. name과 함께 사용하면 체크된 항목만 name=value 형태로 전송됩니다.

참고: value를 지정하지 않으면 기본값 "on"이 전송됩니다.

관심 분야

약관 동의

필수/선택 항목을 구분하여 표시합니다.



API Reference

Props

PropTypeDefaultDescription
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-foundation" <Checkbox /> <Checkbox size="sm" /> <Checkbox defaultChecked /> <Checkbox indeterminate checked /> <Checkbox disabled />

접근성

ARIA 속성

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

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

키보드 네비게이션

  • Tab: 체크박스로 포커스 이동
  • Space: 체크/해제 토글

권장 사항

  • <label htmlFor> 또는 aria-label로 반드시 라벨 연결
  • ✅ 체크박스 그룹에 <fieldset> + <legend> 사용
  • ✅ 에러 상태 시 aria-invalid 속성 추가
  • ❌ 라벨 없이 단독 사용 지양

관련 컴포넌트

  • Switch: 즉시 적용되는 ON/OFF 토글
  • Radio: 단일 선택 옵션
Last updated on