Checkbox

Data Input

하나 이상의 항목을 선택·해제하는 체크박스.

Usage

동의 여부 입력 복수 선택 목록 테이블 행 선택

import

import { Checkbox } from '@mildang/design-system/Checkbox';

예제를 복사해 쓸 때 필요한 준비

• @mildang/icons 를 따로 설치한다. DS 패키지에 아이콘 컴포넌트가 포함되지 않는다.

• @mildang/styled-system 은 이 저장소에서 Panda 가 생성하는 산출물이다. 저장소 안에서는 turbo run ship 이후 쓸 수 있고, 패키지 소비자는 자기 Panda 산출물이나 다른 레이아웃 수단으로 바꿔야 한다.

API Reference

Checkbox Props

Prop

Type

Default

checked

boolean

지정 안 함

description

ReactNode

지정 안 함

endIcon

ReactNode

지정 안 함

error

boolean

지정 안 함

indeterminate

boolean

지정 안 함

label

ReactNode

지정 안 함

onCheckedChange

(checked: boolean) => void

지정 안 함

size

"sm" | "md"

같은 패밀리

@mildang/design-system/Checkbox 에서 같이 내보내는 컴포넌트다.

CheckboxGroup

여러 항목을 함께 선택하는 체크박스 그룹.

사용 가이드

권장

레이블만 읽어도 선택 결과를 알 수 있게 쓴다.
초기 선택은 사용자가 예상할 수 있을 때만 제공한다.

지양

서로 배타적인 선택지를 Checkbox로 표현하지 않는다.

예제

기본 사용

checked 와 onCheckedChange 로 상태를 직접 들고 있는 단일 체크박스 — 동의처럼 하나만 묻는 자리에 씁니다.

코드

Open in Playground

import { useState } from 'react';
import { Checkbox } from '@mildang/design-system/Checkbox';

type CheckboxProps = Parameters<typeof Checkbox>[0];

export default function CheckboxDemoExample(props: CheckboxProps = {}) {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox
      {...{ label: '체크박스', disabled: false, size: 'sm', ...props }}
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

라벨 포함

라벨을 클릭해도 체크 상태가 전환되는 기본형입니다.

코드

Open in Playground

import { useState } from 'react';
import { Checkbox } from '@mildang/design-system/Checkbox';

type CheckboxProps = Parameters<typeof Checkbox>[0];

export default function CheckboxWithLabelExample(props: CheckboxProps = {}) {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox
      {...{ label: '라벨이 있는 체크박스', ...props }}
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

설명 포함

짧은 설명을 함께 표시하는 체크박스입니다.

코드

Open in Playground

import { useState } from 'react';
import { Checkbox } from '@mildang/design-system/Checkbox';

type CheckboxProps = Parameters<typeof Checkbox>[0];

export default function CheckboxWithDescriptionExample(props: CheckboxProps = {}) {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox
      {...{ label: '체크박스', description: 'Description', ...props }}
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

끝 아이콘 포함

라벨 오른쪽에 보조 아이콘을 배치하는 예제입니다.

코드

Open in Playground

import { useState } from 'react';
import { Checkbox } from '@mildang/design-system/Checkbox';
import { IconButton } from '@mildang/design-system/IconButton';
import InfoOutline from '@mildang/icons/react/info-outline';

type CheckboxProps = Parameters<typeof Checkbox>[0];

export default function CheckboxWithEndIconExample(props: CheckboxProps = {}) {
  const [checked, setChecked] = useState(false);
  const defaultEndIcon = (
    <IconButton size="xs">
      <InfoOutline aria-label="info" />
    </IconButton>
  );
  return (
    <Checkbox
      {...{ label: '체크박스', endIcon: defaultEndIcon, ...props }}
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

기본 체크 상태

초기 렌더링부터 체크된 상태로 시작합니다.

코드

Open in Playground

import { Checkbox } from '@mildang/design-system/Checkbox';

type CheckboxProps = Parameters<typeof Checkbox>[0];

export default function CheckboxDefaultCheckedExample(props: CheckboxProps = {}) {
  return <Checkbox {...{ label: '기본값이 체크된 체크박스', defaultChecked: true, ...props }} />;
}

비활성 상태

비활성화된 체크박스는 상호작용할 수 없습니다.

코드

Open in Playground

import { useState } from 'react';
import { Checkbox } from '@mildang/design-system/Checkbox';

type CheckboxProps = Parameters<typeof Checkbox>[0];

export default function CheckboxDisabledExample(props: CheckboxProps = {}) {
  const [checked, setChecked] = useState(false);
  return (
    <Checkbox
      {...{ label: '비활성화된 체크박스', disabled: true, ...props }}
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

가로 그룹

항목이 적을 때 두 체크박스를 가로로 배치합니다.

코드

Open in Playground

import { useState } from 'react';
import { Checkbox } from '@mildang/design-system/Checkbox';

export default function CheckboxGroupHorizontalExample() {
  const [a, setA] = useState(false);
  const [b, setB] = useState(false);
  return (
    <div style={{ display: 'flex', gap: 10, alignItems: 'center' }}>
      <Checkbox label="Label" size="md" description="Description" checked={a} onCheckedChange={setA} />
      <Checkbox label="Label" size="md" description="Description" checked={b} onCheckedChange={setB} />
    </div>
  );
}

세로 그룹

체크박스를 세로로 쌓아 긴 목록의 가독성을 높입니다.

코드

Open in Playground

import { useState } from 'react';
import { Checkbox } from '@mildang/design-system/Checkbox';

export default function CheckboxGroupVerticalExample() {
  const [a, setA] = useState(false);
  const [b, setB] = useState(false);
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
      <Checkbox label="Label" size="md" description="Description" checked={a} onCheckedChange={setA} />
      <Checkbox label="Label" size="md" description="Description" checked={b} onCheckedChange={setB} />
    </div>
  );
}

중간 선택 상태

하위 항목 일부가 선택된 부모를 indeterminate로 표시합니다.

코드

Open in Playground

import { useState } from 'react';
import { Checkbox } from '@mildang/design-system/Checkbox';

export default function CheckboxIndeterminateExample() {
  const [items, setItems] = useState({ item1: false, item2: true, item3: false });
  const allChecked = Object.values(items).every(Boolean);
  const someChecked = Object.values(items).some(Boolean) && !allChecked;
  const handleMainCheckbox = () => {
    const newValue = !allChecked;
    setItems({ item1: newValue, item2: newValue, item3: newValue });
  };
  const handleItemChange = (key: keyof typeof items) => {
    setItems((prev) => ({ ...prev, [key]: !prev[key] }));
  };

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
      <Checkbox
        label="전체 선택"
        checked={allChecked}
        indeterminate={someChecked}
        onCheckedChange={handleMainCheckbox}
      />
      <div style={{ marginLeft: '24px', display: 'flex', flexDirection: 'column', gap: '8px' }}>
        <Checkbox label="항목 1" checked={items.item1} onCheckedChange={() => handleItemChange('item1')} />
        <Checkbox label="항목 2" checked={items.item2} onCheckedChange={() => handleItemChange('item2')} />
        <Checkbox label="항목 3" checked={items.item3} onCheckedChange={() => handleItemChange('item3')} />
      </div>
    </div>
  );
}

커스텀 스타일

sx로 선택 상태의 색상을 덮어쓰는 예제입니다.

코드

Open in Playground

import { Checkbox } from '@mildang/design-system/Checkbox';
import { css } from '@mildang/styled-system/css';

export default function CheckboxCustomStyleExample() {
  return (
    <Checkbox
      label="커스텀 스타일"
      checked
      sx={css.raw({
        '&[data-state="checked"], &[data-state="indeterminate"]': { color: 'yellow.light.800' },
      })}
    />
  );
}