Components

Checkbox

Docs

Checkbox API 사용가이드입니다. 조합 예시는 Overview를 참고하세요.

API

CheckboxGroup · Checkbox · CheckboxItem을 조합합니다. value는 string[]이며 다중 선택을 지원합니다. shape · size · color는 그룹 또는 개별에 전달합니다.

import { CheckboxGroup, Checkbox, CheckboxItem } from "@/components/checkbox";
import { Label } from "@/components/label";

{/* CheckboxItem — 레이블 포함, 다중 선택 */}
<CheckboxGroup
  name="features"
  defaultValue={["a"]}
  className="flex flex-col gap-[var(--gap-8)]"
>
  <CheckboxItem value="a">옵션 A</CheckboxItem>
  <CheckboxItem value="b">옵션 B</CheckboxItem>
</CheckboxGroup>

{/* circle + large */}
<CheckboxGroup
  shape="circle"
  size="large"
  defaultValue={["pro"]}
  className="flex flex-col gap-[var(--gap-8)]"
>
  <CheckboxItem value="free">Free</CheckboxItem>
  <CheckboxItem value="pro">Pro</CheckboxItem>
</CheckboxGroup>

{/* max — 최대 2개 */}
<CheckboxGroup
  max={2}
  defaultValue={["a"]}
  className="flex flex-col gap-[var(--gap-8)]"
>
  <CheckboxItem value="a">A</CheckboxItem>
  <CheckboxItem value="b">B</CheckboxItem>
  <CheckboxItem value="c">C</CheckboxItem>
</CheckboxGroup>

{/* Checkbox + Label */}
<div className="flex items-center gap-[var(--gap-8)]">
  <Checkbox id="agree" name="agree" value="yes" />
  <Label htmlFor="agree">동의합니다</Label>
</div>

Props

Name	Type	Default	Description
`CheckboxGroup.value`	`string[]`	—	제어 모드 선택값 배열. onValueChange와 함께 사용합니다.
`CheckboxGroup.defaultValue`	`string[]`	—	비제어 초기 선택값 배열. Selected + Disabled는 해당 value를 defaultValue에 넣고 disabled합니다.
`CheckboxGroup.max`	`number`	—	최대 선택 개수. 미전달 시 제한 없음. 1 이상 전달 시 1~max개까지 선택 가능합니다.
`CheckboxGroup.shape`	`"square" \| "circle"`	`"square"`	박스 형태. circle은 다중 선택용 원형입니다. 단일 선택은 Radio를 사용하세요.
`CheckboxGroup.size`	`"medium" \| "large"`	`"medium"`	박스 크기.
`CheckboxGroup.color`	`string`	`var(--surface-primary)`	선택(Selected) 배경색. CSS 색 또는 토큰 변수(예: var(--status-success)).
`CheckboxGroup.name`	`string`	—	폼 제출 시 필드 키. 생략 시 자동 생성.
`CheckboxGroup.disabled`	`boolean`	—	그룹 전체 비활성화.
`CheckboxGroup.className`	`string`	—	레이아웃용. 예: flex flex-col gap-… / flex flex-row flex-wrap gap-…
`Checkbox.value`	`string`	—	그룹 내 항목 식별값. 선택 시 value 배열에 포함됩니다.
`Checkbox.shape / size / color`	`동일`	—	개별 오버라이드. 미전달 시 그룹 값을 따릅니다.
`CheckboxItem.children`	`ReactNode`	—	레이블 텍스트.

Events

Name	Signature	Description
`onValueChange`	`(value: string[]) => void`	선택 배열이 바뀔 때 호출됩니다.
`onChange`	`(event: ChangeEvent<HTMLInputElement>) => void`	native checkbox onChange (필요 시).

Notes

소비 앱 필수: React 19, Tailwind CSS v4, ClaBi tokens.css(+ @theme 매핑), clsx.
clsx 유틸이 필수입니다. className 병합에 사용하므로 소비 앱에 clsx가 있어야 합니다.
value/defaultValue/onValueChange는 string[] (다중 선택)입니다.
max 미전달 시 제한 없음. max={1}이면 최대 1개(추가 선택은 기존 항목 해제 후 가능).
shape는 옵션으로 통일합니다. square/circle을 별도 컴포넌트로 나누지 않습니다.
disabled만이면 Disabled(미선택). Selected + Disabled는 defaultValue에 넣고 disabled합니다 (muted 토큰, opacity 아님).
components는 @/shared에 의존하지 않습니다. className 병합은 clsx 직import입니다.