Checkbox

사용자가 체크/체크 해제 상태를 토글할 수 있게 해 주는 컨트롤이에요.

출처: 문서

본문

체크박스는 선택 여부를 나타내는 폼 컨트롤이에요. indeterminate(일부 선택) 상태를 지원하고, 키보드 내비게이션을 완전히 지원하며, 제어/비제어 방식 모두 쓸 수 있어요.

Features

indeterminate(불확정) 상태 지원.
완전한 키보드 내비게이션 지원.
제어(controlled)/비제어(uncontrolled) 방식 모두 지원.

Anatomy

모든 파트를 임포트해 조립해요.

import { Checkbox } from "radix-ui";

export default () => (
  <Checkbox.Root>
    <Checkbox.Indicator />
  </Checkbox.Root>
);

API Reference

Root

체크박스의 모든 파트를 담아요. form 안에서 사용하면 이벤트 전파가 올바르게 되도록 input도 함께 렌더링돼요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`defaultChecked`	`boolean \| 'indeterminate'`	No default value
`checked`	`boolean \| 'indeterminate'`	No default value
`onCheckedChange`	`function`	No default value
`disabled`	`boolean`	No default value
`required`	`boolean`	No default value
`name`	`string`	No default value
`value`	`string`	`on`

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked" \| "indeterminate"`
`[data-disabled]`	Present when disabled

Indicator

체크박스가 checked 또는 indeterminate 상태일 때 렌더링돼요. 이 요소를 직접 스타일하거나, 아이콘을 넣는 래퍼로 사용하거나, 둘 다 할 수 있어요.

Prop	Type	Default
`asChild`	`boolean`	`false`
`forceMount`	`boolean`	No default value

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked" \| "indeterminate"`
`[data-disabled]`	Present when disabled

Examples

Indeterminate(불확정)

체크박스의 상태를 직접 제어해서 indeterminate로 설정할 수 있어요.

import { DividerHorizontalIcon, CheckIcon } from "@radix-ui/react-icons";

import { Checkbox } from "radix-ui";

export default () => {
  const [checked, setChecked] = React.useState("indeterminate");

  return (
    <>
      <StyledCheckbox checked={checked} onCheckedChange={setChecked}>
        <Checkbox.Indicator>
          {checked === "indeterminate" && <DividerHorizontalIcon />}

          {checked === true && <CheckIcon />}
        </Checkbox.Indicator>
      </StyledCheckbox>

      <button
        type="button"
        onClick={() =>
          setChecked((prevIsChecked) =>
            prevIsChecked === "indeterminate" ? false : "indeterminate",
          )
        }
      >
        Toggle indeterminate
      </button>
    </>
  );
};

숨겨진 input 분리하기

기본적으로 Checkbox.Root는 폼 제출을 위해 시각적으로 숨겨진 input을 렌더링해요. 그 input을 재구성하거나 이동하거나 제외하려면, 더 낮은 레벨의 파트들로 체크박스를 조립할 수 있어요.

중요: 이 파트들은 불안정하며 unstable_ 접두사가 붙어 있어서 API가 향후 릴리스에서 바뀔 수 있어요.

Checkbox.unstable_Provider는 체크박스 상태를 제공하고 폼 관련 props(name, value, checked, defaultChecked, required, disabled, onCheckedChange)를 받아요.
Checkbox.unstable_Trigger는 Checkbox.Indicator를 감싸는 상호작용 버튼이에요.
Checkbox.unstable_BubbleInput은 Checkbox.Root가 기본으로 렌더링하는 시각적으로 숨겨진 input이에요. 폼 제출이 필요 없으면 생략해요.

import { Checkbox } from "radix-ui";

export default () => (
  <Checkbox.unstable_Provider name="terms">
    <Checkbox.unstable_Trigger>
      <Checkbox.Indicator />
    </Checkbox.unstable_Trigger>

    <Checkbox.unstable_BubbleInput />
  </Checkbox.unstable_Provider>
);

Accessibility

tri-state Checkbox WAI-ARIA 디자인 패턴을 준수해요.

키보드 상호작용

Key	Description
`Space`	Checks/unchecks the checkbox.

더 알아보기 (Learn more)

indeterminate 상태는 "전체 선택" 같은 부분 선택을 나타낼 때 유용해요.
내부적으로 폼 제출용 숨김 input을 렌더링하므로 name/value props로 폼 값이 전송돼요.