Checkbox

하나의 예/아니오, 또는 여러 개 중 하나입니다. Base UI의 Checkbox 위에 아크릴 체크 표시를 얹었습니다.

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	사용 불가. 색 계열을 버리고 중립 회색이 됩니다

label·description·error가 children이 아니라 prop인 이유는 TextField와 같습니다. 배치는 이미 정해져 있고, 호출하는 쪽이 정하고 싶은 것은 각 자리에 무엇이 들어가는가입니다. children은 아예 받지 않습니다 — 체크박스가 해야 할 말은 셋 중 하나에 들어갑니다.

예시

상태

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>
  );
}

error는 invalid 상태도 함께 켜고, 색 계열 전체를 danger로 옮깁니다 — 체크 표시와 포커스 링, 메시지가 한꺼번에 넘어갑니다.

중간 상태

하위 항목이 서로 다르면 부모는 켜진 것도 꺼진 것도 아닙니다. 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>
  );
}

크기

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>
  );
}

체크박스가 둥글지 않은 이유

체크박스의 모서리 반경은 상자의 약 30%입니다. 컨트롤이 쓰는 약 45%가 아닙니다. --neba-radius-md는 14px이고, 18px 상자에서 그것은 곧 원입니다 — 그리고 둥근 체크박스는 라디오 버튼입니다. 의도는 라이브러리의 다른 곳과 같습니다. 모서리를 잘라낸 시트이지, 알약이 아닙니다.

접근성

• 진짜 role="checkbox"와 그 옆의 숨은 <input>으로 렌더링되므로 폼과 함께 제출됩니다.
• 라벨은 Base UI Field가 컨트롤과 묶어 줍니다. 글자를 눌러도 토글됩니다.
• label이 없다면 aria-label을 주세요.
• indeterminate는 aria-checked="mixed"로 보고됩니다.