Skip to Content
ComponentsFoundationFormCheckbox

Checkbox

선택 항목을 체크하는 체크박스 컴포넌트입니다.

개요

Checkbox는 하나 이상의 옵션을 선택할 수 있는 컴포넌트입니다. Indeterminate 상태를 지원하여 부분 선택을 표현할 수 있습니다.

주요 특징:

  • 단일 / 그룹 체크박스
  • Indeterminate 상태
  • 3가지 Size (sm, md, lg)
  • Label 지원

사용 사례:

  • 약관 동의
  • 다중 선택 옵션
  • 필터 옵션
  • 전체 선택

설치

npx @vortex/cli add checkbox --package foundation

기본 사용법

import { Checkbox } from "@vortex/ui-foundation";
 
export default function Example() {
  return (
    <Checkbox>
      <label>동의합니다</label>
    </Checkbox>
  );
}

Variants (변형)

단일 체크박스

<Checkbox checked={checked} onCheckedChange={setChecked}>
  약관에 동의합니다
</Checkbox>

체크박스 그룹

export default function CheckboxGroup() {
  const [selected, setSelected] = useState([]);
 
  return (
    <div className="space-y-sm">
      <Checkbox
        checked={selected.includes("1")}
        onCheckedChange={(checked) => {
          if (checked) {
            setSelected([...selected, "1"]);
          } else {
            setSelected(selected.filter((id) => id !== "1"));
          }
        }}
      >
        옵션 1
      </Checkbox>
      <Checkbox>옵션 2</Checkbox>
      <Checkbox>옵션 3</Checkbox>
    </div>
  );
}

Indeterminate 상태

<Checkbox checked="indeterminate" onCheckedChange={handleChange}>
  전체 선택 (일부 선택됨)
</Checkbox>

Sizes (크기)

<Checkbox size="sm">Small</Checkbox>
<Checkbox size="md">Medium</Checkbox>
<Checkbox size="lg">Large</Checkbox>

Props API

PropTypeDefaultDescription
checkedboolean | ‘indeterminate’false체크 상태
defaultCheckedbooleanfalse기본 체크 상태
disabledbooleanfalse비활성화 상태
size’sm’ | ‘md’ | ‘lg''md’크기
onCheckedChange(checked) => void-상태 변경 핸들러
classNamestring-추가 CSS 클래스
childrenReactNode-Label 내용

접근성

Checkbox 컴포넌트는 WCAG 2.1 AA 기준을 준수합니다.

ARIA 속성:

  • role="checkbox" (자동 적용)
  • aria-checked (체크 상태)
  • aria-label (Label 없을 경우 필수)

키보드 네비게이션:

  • Space: 체크/해제
  • Tab: 다음 요소로 이동

예제

예제 1: 약관 동의

export default function TermsAgreement() {
  const [agreed, setAgreed] = useState(false);
 
  return (
    <div className="space-y-md">
      <Checkbox checked={agreed} onCheckedChange={setAgreed}>
        [필수] 이용약관에 동의합니다
      </Checkbox>
      <Button disabled={!agreed}>가입하기</Button>
    </div>
  );
}

관련 컴포넌트

Last updated on
TooltipInput