# Checkbox
URL: /lynx/components/checkbox
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/checkbox.mdx

사용자가 여러 옵션 중 하나 이상을 선택할 수 있게 하는 체크박스 컴포넌트입니다.

Lynx Engine 최소 버전: 3.6

사용 가능 버전: @seed-design/lynx-react@0.1.0, @seed-design/lynx-css@0.1.0

## Preview

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import IconCheckmarkFatFill from "@karrotmarket/lynx-monochrome-icon/IconCheckmarkFatFill";
import IconMinusFatFill from "@karrotmarket/lynx-monochrome-icon/IconMinusFatFill";
import { Checkbox, useSeedClassName } from "@seed-design/lynx-react";

function CheckboxItem({
  label,
  defaultChecked = false,
  indeterminate = false,
}: {
  label: string;
  defaultChecked?: boolean;
  indeterminate?: boolean;
}) {
  return (
    <Checkbox.Root
      tone="neutral"
      size="large"
      defaultChecked={defaultChecked}
      indeterminate={indeterminate}
    >
      <Checkbox.Control>
        <Checkbox.Indicator
          checked={<IconCheckmarkFatFill />}
          indeterminate={<IconMinusFatFill />}
        />
      </Checkbox.Control>
      <Checkbox.Label>{label}</Checkbox.Label>
    </Checkbox.Root>
  );
}

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <Checkbox.Group className="checkbox-preview">
        <CheckboxItem label="선택 안 됨" />
        <CheckboxItem label="선택됨" defaultChecked />
        <CheckboxItem label="일부 선택됨" indeterminate />
      </Checkbox.Group>
    </page>
  );
}

root.render(<Root />);
```

<Callout>
  문서 미리보기에서는 아이콘 색상이 적용되지 않아요. 아이콘의 실제 색상은 QR 코드 탭에서 Lynx Explorer를 실행해 확인할 수 있어요.
</Callout>

## Installation

- npm: npx @seed-design/cli add ui:checkbox
- pnpm: pnpm dlx @seed-design/cli add ui:checkbox
- yarn: yarn dlx @seed-design/cli add ui:checkbox
- bun: bun x @seed-design/cli add ui:checkbox

## Usage

설치한 snippet은 compound 구성 요소와 Lynx 아이콘을 한데 묶은 `Checkbox`, 본체만 필요할 때 쓰는 `Checkmark`, 여러 항목을 세로로 묶는 `CheckboxGroup`을 함께 export 합니다.

```tsx
import { Checkbox } from "@/components/ui/checkbox";

export function App() {
  return <Checkbox label="알림 받기" defaultChecked />;
}
```

Controlled 모드는 `checked`와 `onCheckedChange`를 함께 전달합니다.

```tsx
import { useState } from "@lynx-js/react";
import { Checkbox } from "@/components/ui/checkbox";

export function ControlledCheckbox() {
  const [checked, setChecked] = useState(false);

  return (
    <Checkbox
      label={checked ? "선택됨" : "선택 안 됨"}
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}
```

### Indeterminate 상태

일부 항목만 선택된 상태를 표현할 때 `indeterminate` prop을 사용합니다. Indeterminate 상태에서 tap하면 `checked` 값만 토글되며, `indeterminate` 값은 소비자가 직접 해제해야 합니다.

```tsx
import { useState } from "@lynx-js/react";
import { Checkbox } from "@/components/ui/checkbox";

export function SelectAllCheckbox() {
  const [checked, setChecked] = useState(false);
  const [indeterminate, setIndeterminate] = useState(true);

  return (
    <Checkbox
      label="전체 선택"
      checked={checked}
      indeterminate={indeterminate}
      onCheckedChange={(nextChecked) => {
        setChecked(nextChecked);
        setIndeterminate(false);
      }}
    />
  );
}
```

### Group 레이아웃

여러 Checkbox를 수직 간격과 함께 묶을 때 `CheckboxGroup`을 사용합니다. 자식 Checkbox 사이의 상태 공유는 하지 않고 레이아웃만 제공합니다.

```tsx
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export function NotificationSettings() {
  return (
    <CheckboxGroup>
      <Checkbox label="채팅 알림" defaultChecked />
      <Checkbox label="관심 키워드 알림" />
      <Checkbox label="마케팅 정보 수신" />
    </CheckboxGroup>
  );
}
```

Label 없이 본체만 쓰고 싶다면 `Checkmark`를 사용합니다.

```tsx
import { Checkmark } from "@/components/ui/checkbox";

export function App() {
  return <Checkmark variant="ghost" tone="brand" defaultChecked />;
}
```

### Tone / Variant

`Checkbox`와 `Checkmark`는 snippet API에서 `tone`, `variant`를 그대로 전달받습니다.

```tsx
import { Checkbox, Checkmark } from "@/components/ui/checkbox";

export function CheckboxVariants() {
  return (
    <>
      <Checkbox label="브랜드 체크박스" tone="brand" defaultChecked />
      <Checkmark variant="ghost" tone="brand" defaultChecked />
    </>
  );
}
```

## Props

### `Checkbox`

### `Checkmark`

### `CheckboxGroup`

## Examples

### Sizes

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import IconCheckmarkFatFill from "@karrotmarket/lynx-monochrome-icon/IconCheckmarkFatFill";
import { Checkbox, HStack, VStack, useSeedClassName } from "@seed-design/lynx-react";

function CheckboxItem({
  label,
  size,
  variant,
}: {
  label: string;
  size: Checkbox.RootProps["size"];
  variant: Checkbox.RootProps["variant"];
}) {
  return (
    <Checkbox.Root tone="neutral" size={size} variant={variant} defaultChecked>
      <Checkbox.Control>
        <Checkbox.Indicator
          unchecked={variant === "ghost" ? <IconCheckmarkFatFill /> : undefined}
          checked={<IconCheckmarkFatFill />}
        />
      </Checkbox.Control>
      <Checkbox.Label>{label}</Checkbox.Label>
    </Checkbox.Root>
  );
}

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <HStack className="checkbox-preview" gap="x8">
        <VStack gap="spacingY.componentDefault">
          <CheckboxItem label="Medium (default)" size="medium" variant="square" />
          <CheckboxItem label="Large" size="large" variant="square" />
        </VStack>
        <VStack gap="spacingY.componentDefault">
          <CheckboxItem label="Medium (default)" size="medium" variant="ghost" />
          <CheckboxItem label="Large" size="large" variant="ghost" />
        </VStack>
      </HStack>
    </page>
  );
}

root.render(<Root />);
```

### Disabled

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import IconCheckmarkFatFill from "@karrotmarket/lynx-monochrome-icon/IconCheckmarkFatFill";
import { Checkbox, VStack, useSeedClassName } from "@seed-design/lynx-react";

function CheckboxItem({
  label,
  variant,
  defaultChecked = false,
}: {
  label: string;
  variant: Checkbox.RootProps["variant"];
  defaultChecked?: boolean;
}) {
  return (
    <Checkbox.Root
      tone="neutral"
      size="large"
      variant={variant}
      defaultChecked={defaultChecked}
      disabled
    >
      <Checkbox.Control>
        <Checkbox.Indicator
          unchecked={variant === "ghost" ? <IconCheckmarkFatFill /> : undefined}
          checked={<IconCheckmarkFatFill />}
        />
      </Checkbox.Control>
      <Checkbox.Label>{label}</Checkbox.Label>
    </Checkbox.Root>
  );
}

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <page className={seedClassName}>
      <VStack className="checkbox-preview" gap="spacingY.componentDefault">
        <CheckboxItem label="선택 안 됨, Square" variant="square" />
        <CheckboxItem label="선택됨, Square" variant="square" defaultChecked />
        <CheckboxItem label="선택 안 됨, Ghost" variant="ghost" />
        <CheckboxItem label="선택됨, Ghost" variant="ghost" defaultChecked />
      </VStack>
    </page>
  );
}

root.render(<Root />);
```

### Listening to Value Changes

`onCheckedChange`로 체크박스의 선택 상태 변경을 감지할 수 있습니다.

```tsx
import "./styles";

import { root, useState } from "@lynx-js/react";
import IconCheckmarkFatFill from "@karrotmarket/lynx-monochrome-icon/IconCheckmarkFatFill";
import { Checkbox, VStack, useSeedClassName } from "@seed-design/lynx-react";

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [count, setCount] = useState(0);
  const [lastValue, setLastValue] = useState<boolean | null>(null);

  return (
    <page className={seedClassName}>
      <VStack className="checkbox-preview" gap="x4">
        <Checkbox.Root
          tone="neutral"
          size="large"
          onCheckedChange={(checked) => {
            setCount((previous) => previous + 1);
            setLastValue(checked);
          }}
        >
          <Checkbox.Control>
            <Checkbox.Indicator checked={<IconCheckmarkFatFill />} />
          </Checkbox.Control>
          <Checkbox.Label>선택 상태 바꾸기</Checkbox.Label>
        </Checkbox.Root>
        <text className="checkbox-preview__status">
          onCheckedChange 호출: {count}회, 마지막 값: {JSON.stringify(lastValue)}
        </text>
      </VStack>
    </page>
  );
}

root.render(<Root />);
```

## 웹 버전과의 차이

<Callout type="warning">
  Lynx `Checkbox`는 React `Checkbox`와 다음과 같은 차이가 있습니다.

  - **아이콘 주입 방식**: snippet의 `Checkbox`와 `Checkmark`는 `@karrotmarket/lynx-monochrome-icon`의 check / minus icon을 자동으로 주입합니다. compound component를 직접 조합할 때는 `Checkbox.Indicator`에 Lynx monochrome icon을 전달해야 합니다. raw `<svg>` 주입은 Lynx 범위 밖입니다.
  - **이벤트 핸들링**: `onChange` 대신 `onCheckedChange`만 노출합니다. tap 핸들러는 Root 내부에서 소유합니다.
  - **Pressed 상태**: 웹의 `data-active` 대신 내부 press state를 `checkmark` recipe의 `pressed` boolean variant로 전달합니다.
  - **렌더링 요소**: HTML `<label>` / `<input>` 대신 네이티브 `<view>` / `<text>` 요소를 렌더링합니다.
  - **Compound 구조**: `Checkbox.Root` → `Checkbox.Control` → `Checkbox.Indicator` + `Checkbox.Label` 구성과 Context로 상태/variant를 공유하는 흐름은 동일합니다.
  - **ref forwarding**: `Checkbox`, `Checkmark`, `CheckboxGroup`은 Root view로 ref를 전달합니다. 웹 snippet처럼 hidden input ref를 제공하지 않습니다.
</Callout>

## Lynx 미지원 기능

현재 Lynx 플랫폼 제약으로 다음 기능이 지원되지 않습니다.

### 런타임 모델 차이로 제외

| 기능                                        | 웹 대응                      | 설명                                               |
| ----------------------------------------- | ------------------------- | ------------------------------------------------ |
| `CheckboxHiddenInput`                     | `<input type="checkbox">` | Lynx에 HTML form 제출 모델 없음                         |
| `inputProps`                              | hidden input props        | Lynx snippet은 hidden input을 렌더링하지 않음             |
| `name` / `value` / `required` / `invalid` | form field props          | Lynx에 native form 제출 모델 없음                       |
| `focus` / `focusVisible`                  | 키보드 포커스                   | Lynx에 키보드 포커스 개념 없음                              |
| `onChange` (raw DOM event)                | `React.ChangeEvent`       | 의미 없음. `onCheckedChange`로 대체                     |
| `weight="default"` / `"stronger"`         | deprecated 호환 매핑          | Lynx 신규 컴포넌트이므로 처음부터 `"regular"` / `"bold"` 만 노출 |