체크박스 그룹

체크박스 그룹 (Checkbox Group)

한 번에 여러 옵션을 선택할 수 있는 상호작용 버튼의 집합이에요. div 요소 기반으로 만들어졌어요.

출처: 문서

본문

한 번에 여러 옵션을 선택할 수 있는 상호작용 버튼의 집합이에요.

<CheckboxGroup.Root defaultValue={["1"]} name="example">
  <CheckboxGroup.Item value="1">Fun</CheckboxGroup.Item>

  <CheckboxGroup.Item value="2">Serious</CheckboxGroup.Item>

  <CheckboxGroup.Item value="3">Smart</CheckboxGroup.Item>
</CheckboxGroup.Root>

API Reference

이 컴포넌트는 div 요소를 기반으로 하며 공통 margin props를 지원해요.

Root

체크박스 그룹의 모든 부분을 담고 있어요.

Prop Type Default
asChild boolean No default value
size Responsive<"1" | "2" | "3"> "2"
variant "classic" | "surface" | "soft" "surface"
color enum No default value
highContrast boolean No default value

Item

그룹에서 선택(체크)할 수 있는 항목이에요.

예제 (Examples)

Size

size prop으로 체크박스 크기를 제어해요.

<Flex align="center" gap="2">
  <CheckboxGroup.Root size="1" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root size="2" defaultValue={["2"]}>
    <CheckboxGroup.Item value="2" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root size="3" defaultValue={["3"]}>
    <CheckboxGroup.Item value="3" />
  </CheckboxGroup.Root>
</Flex>

Variant

variant prop으로 체크박스들의 시각적 스타일을 제어해요.

<Flex gap="2">
  <Flex direction="column" asChild gap="2">
    <CheckboxGroup.Root variant="surface" defaultValue={["1"]}>
      <CheckboxGroup.Item value="1" />

      <CheckboxGroup.Item value="2" />
    </CheckboxGroup.Root>
  </Flex>

  <Flex direction="column" asChild gap="2">
    <CheckboxGroup.Root variant="classic" defaultValue={["1"]}>
      <CheckboxGroup.Item value="1" />

      <CheckboxGroup.Item value="2" />
    </CheckboxGroup.Root>
  </Flex>

  <Flex direction="column" asChild gap="2">
    <CheckboxGroup.Root variant="soft" defaultValue={["1"]}>
      <CheckboxGroup.Item value="1" />

      <CheckboxGroup.Item value="2" />
    </CheckboxGroup.Root>
  </Flex>
</Flex>

Color

color prop으로 특정 color를 지정해요.

<Flex gap="2">
  <CheckboxGroup.Root color="indigo" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="cyan" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="orange" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="crimson" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>
</Flex>

High-contrast

highContrast prop으로 배경과의 색 대비를 높여요.

<Grid rows="2" gap="2" display="inline-grid" flow="column">
  <CheckboxGroup.Root color="indigo" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="indigo" defaultValue={["1"]} highContrast>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="cyan" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="cyan" defaultValue={["1"]} highContrast>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="orange" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="orange" defaultValue={["1"]} highContrast>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="crimson" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="crimson" defaultValue={["1"]} highContrast>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="gray" defaultValue={["1"]}>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>

  <CheckboxGroup.Root color="gray" defaultValue={["1"]} highContrast>
    <CheckboxGroup.Item value="1" />
  </CheckboxGroup.Root>
</Grid>

Alignment

CheckboxGroup.Item을 Text 안에 구성하면 텍스트의 첫 줄과 자동으로 중앙 정렬돼요.

<Flex direction="column" gap="3">
  <CheckboxGroup.Root size="1" defaultValue={["1"]}>
    <Text as="label" size="2">
      <Flex gap="2">
        <CheckboxGroup.Item value="1" /> Default
      </Flex>
    </Text>

    <Text as="label" size="2">
      <Flex gap="2">
        <CheckboxGroup.Item value="2" /> Compact
      </Flex>
    </Text>
  </CheckboxGroup.Root>

  <CheckboxGroup.Root size="2" defaultValue={["1"]}>
    <Text as="label" size="3">
      <Flex gap="2">
        <CheckboxGroup.Item value="1" /> Default
      </Flex>
    </Text>

    <Text as="label" size="3">
      <Flex gap="2">
        <CheckboxGroup.Item value="2" /> Compact
      </Flex>
    </Text>
  </CheckboxGroup.Root>

  <CheckboxGroup.Root size="3" defaultValue={["1"]}>
    <Text as="label" size="4">
      <Flex gap="2">
        <CheckboxGroup.Item value="1" /> Default
      </Flex>
    </Text>

    <Text as="label" size="4">
      <Flex gap="2">
        <CheckboxGroup.Item value="2" /> Compact
      </Flex>
    </Text>
  </CheckboxGroup.Root>
</Flex>

여러 줄 텍스트와도 자동으로 잘 정렬돼요.

Disabled

네이티브 disabled 속성을 사용해 비활성화된 체크박스를 만들 수 있어요.

<Flex direction="column" gap="2">
  <CheckboxGroup.Root defaultValue={["2"]}>
    <CheckboxGroup.Item value="1">Off</CheckboxGroup.Item>

    <CheckboxGroup.Item value="2">On</CheckboxGroup.Item>
  </CheckboxGroup.Root>

  <CheckboxGroup.Root defaultValue="2">
    <CheckboxGroup.Item value="1" disabled>
      Off
    </CheckboxGroup.Item>

    <CheckboxGroup.Item value="2" disabled>
      On
    </CheckboxGroup.Item>
  </CheckboxGroup.Root>
</Flex>

더 알아보기 (Learn more)