Checkbox

켜고 끌 수 있는 하나의 항목입니다. 폼과 함께 제출되는 boolean 값이나, 여러 개를 동시에 고르는 목록에 씁니다.

import { Checkbox } from 'neba';

<Checkbox label="로그인 상태 유지" defaultChecked />;

Props

Prop	타입	기본값	설명
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	높이와 타입 스케일
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
label	ReactNode	—	컨트롤과 연결되는 라벨. Base UI Field가 묶어 줍니다
description	ReactNode	—	보조 설명
error	ReactNode	—	오류 메시지. 값이 있으면 invalid 상태도 함께 켜지고 색 계열이 danger로 넘어갑니다
invalid	boolean	!!error	메시지 없이 invalid만 켭니다. 외부 폼 라이브러리가 유효성을 가질 때
checked	boolean	—	체크 여부. onCheckedChange와 함께 제어 컴포넌트로 씁니다
defaultChecked	boolean	false	초기 체크 여부
onCheckedChange	(checked: boolean, details) => void	—	체크 상태가 바뀔 때
indeterminate	boolean	false	켜짐도 꺼짐도 아닌 중간 상태. 하위 항목 일부만 체크된 부모 체크박스
required	boolean	false	폼 제출 전에 반드시 체크해야 함
name	string	—	폼 제출 시의 필드 이름
readOnly	boolean	false	값은 보이지만 바꿀 수 없음. 색과 가장자리는 유지한 채 채도만 빠집니다
disabled	boolean	false	사용 불가. 색 계열을 버리고 중립 회색이 됩니다
classNames	NebaSlots<'label' | 'control' | 'description' | 'error' | 'indicator'>	—	루트 뒤에 있는 각 파트의 class. 루트 자체는 className이 맡으므로 root 키는 없습니다

label · description · error는 children이 아니라 prop입니다. children은 받지 않습니다.

즉시 효력이 생기는 설정이라면 Switch를 쓰세요. Checkbox는 저장 버튼과 함께 제출되는 값입니다.

예시

checked와 onCheckedChange

checked와 onCheckedChange로 controlled, defaultChecked로 uncontrolled 컴포넌트가 됩니다.

disabled · readOnly · error

error에 메시지를 주면 invalid 상태가 함께 켜지고 색 계열이 danger로 옮겨갑니다. 체크 표시와 focus ring, 메시지가 한꺼번에 바뀝니다.

import { Checkbox } from 'neba';

export default function CheckboxStates() {
  return (
    <div className="flex flex-col gap-3">
      <Checkbox label="Unchecked" />
      <Checkbox label="Checked" defaultChecked />
      <Checkbox label="Read-only" readOnly defaultChecked />
      <Checkbox label="Disabled" disabled />
      <Checkbox label="Disabled and checked" disabled defaultChecked />
      <Checkbox label="I agree to the terms" error="You have to agree to continue." />
    </div>
  );
}

indeterminate

하위 항목의 상태가 서로 다를 때 부모 Checkbox에 쓰는 세 번째 겉모습입니다. 값 자체는 여전히 켜짐 또는 꺼짐이며, indeterminate는 표시에만 관여합니다.

import { useState } from 'react';
import { Checkbox } from 'neba';

const SCOPES = ['Read', 'Write', 'Delete'];

export default function CheckboxIndeterminate() {
  const [checked, setChecked] = useState([true, false, false]);
  const all = checked.every(Boolean);
  const some = checked.some(Boolean);

  return (
    <div className="flex flex-col gap-3">
      <Checkbox
        label="All permissions"
        checked={all}
        indeterminate={some && !all}
        onCheckedChange={(next) => setChecked(checked.map(() => next))}
      />
      <div className="ms-6 flex flex-col gap-3">
        {SCOPES.map((scope, index) => (
          <Checkbox
            key={scope}
            label={scope}
            checked={checked[index]}
            onCheckedChange={(next) =>
              setChecked(checked.map((value, i) => (i === index ? next : value)))
            }
          />
        ))}
      </div>
    </div>
  );
}

size

import { Checkbox } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function CheckboxSizes() {
  return (
    <div className="flex flex-col gap-3">
      {SIZES.map((size) => (
        <Checkbox key={size} size={size} label={size} defaultChecked />
      ))}
    </div>
  );
}

classNames

className은 tick이 아니라 감싸는 field wrapper에 붙습니다. tick과 그 안의 표시는 classNames로 갑니다.

<Checkbox label="I agree" classNames={{ control: 'rounded-full', label: 'font-medium' }} />

slot은 label, control, indicator, description, error입니다. control은 tick 자체(체크되면 채워지는 테두리 상자)이고 indicator는 그 안의 표시입니다. 넘긴 class가 컴포넌트 자신의 class와 어떻게 겨루는지는 prop 규약을 보세요.

접근성

• role="checkbox"와 함께 숨은 <input>이 렌더링되므로 name을 주면 폼과 함께 제출됩니다.
• 라벨이 컨트롤과 연결되어 있어 글자를 눌러도 토글됩니다.
• label을 쓰지 않는다면 aria-label을 주세요.
• indeterminate는 aria-checked="mixed"로 보고됩니다.