체크박스

체크박스 (Checkbox)

사용자가 여러 옵션 중 여러 값을 선택해야 할 때 폼에서 사용하는 컴포넌트예요. 선택 여부를 표시하는 인디케이터와 라벨을 함께 제공해요.

출처: 문서

본문

사용법 (Usage)

import { Checkbox } from "@chakra-ui/react"

<Checkbox.Root>
  <Checkbox.HiddenInput />
  <Checkbox.Control>
    <Checkbox.Indicator />
  </Checkbox.Control>
  <Checkbox.Label />
</Checkbox.Root>

:::info

닫힌 컴포넌트 조합(closed component composition)을 선호한다면, 아래 스니펫을 확인해 보세요.

:::

단축 기능 (Shortcuts)

Checkbox 컴포넌트는 자주 쓰이는 사용 사례를 위한 단축 기능 집합도 제공해요.

CheckboxControl

이 컴포넌트는 기본적으로 Checkbox.Indicator를 그 안에 렌더링해요.

이렇게 써도 되고:

<Checkbox.Control>
  <Checkbox.Indicator />
</Checkbox.Control>

인디케이터를 커스터마이즈할 필요가 없다면, 이렇게 더 간결하게 쓸 수도 있어요:

<Checkbox.Control />

예제 (Examples)

변형 (Variants)

Checkbox.Root 컴포넌트에 variant prop을 전달해 체크박스의 시각적 스타일을 바꿀 수 있어요.

색상 (Colors)

Checkbox.Root 컴포넌트에 colorPalette prop을 전달해 체크박스의 색상을 바꿀 수 있어요.

크기 (Sizes)

Checkbox.Root 컴포넌트에 size prop을 전달해 체크박스의 크기를 바꿀 수 있어요.

상태 (States)

Checkbox.Root 컴포넌트에 disabled 또는 invalid prop을 전달해 체크박스의 시각적 상태를 바꿀 수 있어요.

제어 (Controlled)

checked와 onCheckedChange prop을 사용해 체크박스의 상태를 제어할 수 있어요.

라벨 위치 (Label Position)

라벨 위치를 오른쪽으로 바꾸는 예시예요.

스토어 (Store)

체크박스를 제어하는 또 다른 방법으로 RootProvider 컴포넌트와 useCheckbox 스토어 훅을 사용할 수 있어요.

이렇게 하면 체크박스 바깥에서도 체크박스 상태와 메서드에 접근할 수 있어요.

구성 (Composition)

체크박스를 필드 컴포넌트와 조합하는 예시예요.

Hook Form

Checkbox 컴포넌트를 react-hook-form 라이브러리와 함께 사용하는 예시예요.

그룹 (Group)

CheckboxGroup 컴포넌트를 사용해 여러 체크박스를 함께 묶을 수 있어요.

그룹 Hook Form (Group Hook Form)

CheckboxGroup 컴포넌트를 react-hook-form 라이브러리와 함께 사용하는 예시예요.

커스텀 아이콘 (Custom Icon)

Checkbox.Control 안에 커스텀 아이콘을 렌더링해 체크박스의 아이콘을 바꿀 수 있어요.

불확정 상태 (Indeterminate)

checked prop을 indeterminate로 설정해 체크박스를 불확정(indeterminate) 상태로 보여줄 수 있어요.

설명 (Description)

체크박스에 추가 설명을 넣는 예시예요.

링크 (Link)

Checkbox.Label 안에 앵커 태그를 렌더링해 라벨에 링크를 추가할 수 있어요.

닫힌 컴포넌트 (Closed Component)

Checkbox를 닫힌 컴포넌트 조합으로 설정하는 방법이에요.

닫힌 컴포넌트를 프로젝트에 자동으로 추가하려면 다음 명령을 실행하세요:

npx @chakra-ui/cli snippet add checkbox

이렇게 사용해요:

<Checkbox>Accept terms and conditions</Checkbox>

가이드 (Guides)

CheckboxGroup + Field vs Fieldset

여러 체크박스를 다룰 때, Field와 Fieldset의 의미적 차이를 이해하는 것이 중요해요:

단일 체크박스 (Single Checkbox): 라벨과 도움말 텍스트가 있는 올바른 폼 필드 구조를 위해 Field.Root로 감싸세요
CheckboxGroup: Field.Root가 아니라 Fieldset.Root로 감싸세요

체크박스 그룹은 관련 옵션들의 모음이므로, 단일 필드가 아니라 legend가 있는 fieldset으로 마크업해야 해요. CheckboxGroup을 Field.Root로 감싸면 첫 번째 체크박스만 클릭에 반응하는 상호작용 문제가 발생할 수 있어요.

✅ 올바른 사용법:

<Fieldset.Root>
  <CheckboxGroup name="framework">
    <Fieldset.Legend>Select framework</Fieldset.Legend>
    {/* ... checkboxes ... */}
  </CheckboxGroup>
</Fieldset.Root>

❌ 잘못된 사용법:

// Don't wrap CheckboxGroup with Field.Root
<Field.Root>
  <CheckboxGroup>{/* ... checkboxes ... */}</CheckboxGroup>
</Field.Root>

Props

Root

탐색기 (Explorer)

Checkbox 컴포넌트의 파트들을 인터랙티브하게 탐색해 보세요. 사이드바에서 파트를 클릭하면 미리보기에서 해당 파트가 강조 표시돼요.

더 알아보기 (Learn more)

체크박스 카드 (Checkbox Card) — 카드 안의 선택 옵션
Ark UI 체크박스 — 체크박스의 동작 로직