FE ChapterDesign SystemAction
Checkbox
여러 항목을 선택/해제할 수 있는 입력 컴포넌트입니다. 폼·테이블·체크리스트에서 사용합니다.
개요
- 다중 선택, 전체 선택/해제, 행 단위 선택
- 폼에서 약관 동의, 옵션 토글
이렇게 활용하세요
✅ 권장 사용 방식
-
폼 / 동의
- 필수·선택 동의를 구분해 보여주고, 빠뜨린 항목은 에러 메시지로 바로 알려줍니다.
- '전체 동의'는 상단에서 한 번에 체크하고, 하위 항목들은 각각 선택할 수 있게 합니다.
-
리스트 / 테이블
- 헤더에 '전체 선택'을 두고, 행마다 개별 선택을 지원하며 선택 개수도 함께 보여줍니다.
- 표의 정보 밀도가 높다면 마우스 호버 시 체크박스가 나타나게 합니다.
-
그룹 / 계층
- 일부만 선택되면 부모는 "-" 표시로 부분 선택을 표기합니다(indeterminate).
- 부모를 체크하면 전부 선택되며, 해제하면 전부 해제되도록 동기화합니다.
-
모바일 / 접근성
- 손가락으로 누르기 편한 크기의 라벨을 늘려도 체크가 토글되게 합니다.
- 스크린리더가 상태를 인식하도록 aria-checked="mixed"와 설명 연결을 적용합니다.
❌ 비권장 사례
-
폼 / 동의
- 여러 약관을 한 체크박스에 묶어 통합 동의만 받는 것을 금지합니다.
- 필수 항목을 빠뜨려도 제출이 되고 나중에야 오류를 알리는 것을 금지합니다.
-
리스트 / 테이블
- 단일 선택만 필요한 목록에 체크박스를 써서 헷갈리게 하는 것을 금지합니다.
- 헤더의 전체 선택 없이 행마다 두어 일괄 선택/해제가 안 되게 하는 것을 금지합니다.
-
그룹 / 계층
- 자식 일부 선택인데 부모를 체크로 표시해 사용자가 혼란을 겪게 합니다.
- 부모를 눌러도 자식 상태가 동기화되지 않는 상호작용을 금지합니다.
-
모바일 / 접근성
- 체크박스·라벨이 너무 작아 손가락으로 누르기 어렵게 구성합니다.
- 라벨을 늘려도 토글되지 않아 작은 박스만 정확히 눌러야 하게 만듭니다.
Variants
With Label
가장 기본형으로 라벨 클릭만으로도 토글되도록 연결된 체크박스입니다.
Unchecked
Checked
Disabled
<Checkbox label="라벨이 있는 체크박스" />
<Checkbox label="라벨이 있는 체크박스" defaultChecked />
<Checkbox label="비활성화된 체크박스" disabled />With Description
짧은 설명(1–2줄)로 추가 맥락을 제공하는 체크박스입니다. 약관/폼에 적합합니다.
Unchecked
Description
Checked
Description
Disabled
Description
<Checkbox label="체크박스" description="Description" />
<Checkbox label="체크박스" description="Description" defaultChecked />
<Checkbox label="체크박스" description="Description" disabled />With End Icon
라벨 우측에 아이콘을 표시하여 의미를 보강하는 체크박스입니다. 과도한 장식은 지양합니다.
Unchecked
Checked
Disabled
<Checkbox
label="체크박스"
endIcon={
<IconButton size="xSmall">
<InfoOutline aria-label="info" />
</IconButton>
}
/>Indeterminate State
전체 선택 체크박스에서 일부 항목만 선택되었을 때의 중간 상태(indeterminate)를 보여주는 체크박스입니다.
<Checkbox label="전체 선택" indeterminate />
<div className="ml-6 flex flex-col gap-2">
<Checkbox label="항목 1" />
<Checkbox label="항목 2" defaultChecked />
<Checkbox label="항목 3" />
</div>Sizes
체크박스는 사용 맥락에 따라 두 가지 사이즈로 제공됩니다. 상황과 밀도에 맞춰 선택합니다.
<Checkbox size="medium" label="medium" />
<Checkbox size="small" label="small" />| Size Name | Use Case |
|---|---|
| medium | 폼·리스트·테이블 등 대부분의 기본 상황 |
| small | 데이터 그리드·카드 내부 등 조밀 레이아웃(PC 우선, 모바일 핵심 입력엔 비권장) |
Group Layouts
Horizontal Group
항목이 적을 때 가로 정렬로 한눈에 비교·선택이 쉽습니다.
Description
Description
<div className="flex gap-4 items-center">
<Checkbox label="Label" size="medium" description="Description" />
<Checkbox label="Label" size="medium" description="Description" />
</div>Vertical Group
라벨이 길거나 항목이 많을 때 세로 스택으로 가독성과 스크롤을 확보합니다.
Description
Description
<div className="flex flex-col gap-1">
<Checkbox label="Label" size="medium" description="Description" />
<Checkbox label="Label" size="medium" description="Description" />
</div>Controlled State
상태를 외부에서 관리하는 체크박스입니다.
import { useState } from 'react';
function ControlledCheckbox() {
const [checked, setChecked] = useState(false);
return (
<Checkbox
label="Controlled Checkbox"
checked={checked}
onCheckedChange={setChecked}
/>
);
}With Ref
ref를 사용하여 체크박스에 직접 접근할 수 있습니다.
import { useRef } from 'react';
function CheckboxWithRef() {
const ref = useRef<HTMLButtonElement>(null);
const handleClick = () => {
console.log(ref.current);
};
return (
<Checkbox ref={ref} label="Checkbox with Ref" />
);
}Props
| Prop | Type | Default |
|---|---|---|
checked? | boolean | undefined |
indeterminate? | boolean | false |
onCheckedChange? | (checked: boolean) => void | undefined |
defaultChecked? | boolean | false |
size? | "small" | "medium" | "small" |
label? | string | undefined |
description? | string | undefined |
endIcon? | React.ReactNode | undefined |
disabled? | boolean | false |
required? | boolean | false |
name? | string | undefined |
value? | string | undefined |
id? | string | undefined |
Edit on GitHub
Last updated on