체크박스 카드

체크박스 카드 (Checkbox Card)

카드 안에 표시된 옵션을 선택하거나 해제할 때 사용하는 컴포넌트예요. 카드 형태로 더 풍부한 콘텐츠를 담아 선택 여부를 표현할 수 있어요.

출처: 문서

본문

사용법 (Usage)

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

<CheckboxCard.Root>
  <CheckboxCard.HiddenInput />
  <CheckboxCard.Control>
    <CheckboxCard.Content>
      <CheckboxCard.Label />
      <CheckboxCard.Description />
    </CheckboxCard.Content>
    <CheckboxCard.Indicator />
  </CheckboxCard.Control>
</CheckboxCard.Root>

:::info

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

:::

예제 (Examples)

설명 (Description)

CheckboxCard.Description 컴포넌트를 사용해 체크박스 카드에 설명을 추가할 수 있어요.

그룹 (Group)

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

크기 (Sizes)

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

변형 (Variants)

CheckboxCard.Root 컴포넌트에 variant prop을 전달해 체크박스 카드의 변형을 바꿀 수 있어요.

비활성 (Disabled)

CheckboxCard.Root 컴포넌트에 disabled prop을 전달해 체크박스 카드를 비활성화할 수 있어요.

애드온 (Addon)

CheckboxCard.Addon 컴포넌트 안에 추가 콘텐츠를 렌더링해 체크박스 카드에 더 많은 컨텍스트를 더할 수 있어요.

인디케이터 없음 (No Indicator)

인디케이터 없이 체크박스 카드를 사용하는 예시예요.

아이콘 (Icon)

체크박스 카드 안에 커스텀 아이콘을 렌더링하는 예시예요.

닫힌 컴포넌트 (Closed Component)

체크박스 카드를 닫힌 컴포넌트 조합으로 설정하는 방법이에요.

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

npx @chakra-ui/cli snippet add checkbox-card

이렇게 사용해요:

<CheckboxCard label="Checkbox Card" />

가이드 (Guides)

CheckboxGroup + Field vs Fieldset

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

  • 단일 CheckboxCard: 라벨과 도움말 텍스트가 있는 올바른 폼 필드 구조를 위해 Field.Root로 감쌀 수 있어요
  • CheckboxGroup: Field.Root가 아니라 Fieldset.Root로 감싸야 해요

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

✅ 올바른 사용법:

<Fieldset.Root>
  <CheckboxGroup name="framework">
    <Fieldset.Legend>Select framework(s)</Fieldset.Legend>
    {/* ... checkbox cards ... */}
  </CheckboxGroup>
</Fieldset.Root>

❌ 잘못된 사용법:

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

Props

Root

탐색기 (Explorer)

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

더 알아보기 (Learn more)