# 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 { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <VStack className="checkbox-preview">
        <CheckboxGroup
          label="관심 분야"
          description="관심 있는 분야를 모두 선택해 주세요."
          indicator="선택"
        >
          <Checkbox label="디자인" tone="neutral" size="large" />
          <Checkbox label="개발" tone="neutral" size="large" defaultChecked />
          <Checkbox label="마케팅" tone="neutral" size="large" />
        </CheckboxGroup>
      </VStack>
    </view>
  );
}
```

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

## Installation

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

## Props

### `CheckboxGroup`

### `Checkbox`

### `Checkmark`

### 접근성 이름

`Checkbox.Root`는 기본적으로 접근성 요소로 노출됩니다. `checkbox` 역할과 현재 선택 상태, 비활성 상태도 전달합니다. Registry `Checkbox`에 문자열 `label`을 전달하면 화면의 문구를 `accessibility-label`에도 연결합니다. 문자열이 아닌 `label`이나 `children`으로 문구를 구성할 때는 같은 내용을 `accessibility-label`에 직접 전달하세요.

## Examples

### Sizes

```tsx
import "./styles";

import { HStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <HStack className="checkbox-preview" gap="x8">
        <CheckboxGroup>
          <Checkbox label="Medium (default)" size="medium" defaultChecked tone="neutral" />
          <Checkbox label="Large" size="large" defaultChecked tone="neutral" />
        </CheckboxGroup>
        <CheckboxGroup>
          <Checkbox
            label="Medium (default)"
            size="medium"
            variant="ghost"
            defaultChecked
            tone="neutral"
          />
          <Checkbox label="Large" size="large" variant="ghost" defaultChecked tone="neutral" />
        </CheckboxGroup>
      </HStack>
    </view>
  );
}
```

### Tones and Variants

#### Brand

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <VStack className="checkbox-preview">
        <CheckboxGroup>
          <Checkbox
            label="Square (default)"
            variant="square"
            tone="brand"
            size="large"
            defaultChecked
          />
          <Checkbox label="Ghost" variant="ghost" tone="brand" size="large" defaultChecked />
        </CheckboxGroup>
      </VStack>
    </view>
  );
}
```

#### Neutral

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <VStack className="checkbox-preview">
        <CheckboxGroup>
          <Checkbox
            label="Square (default)"
            variant="square"
            tone="neutral"
            size="large"
            defaultChecked
          />
          <Checkbox label="Ghost" variant="ghost" tone="neutral" size="large" defaultChecked />
        </CheckboxGroup>
      </VStack>
    </view>
  );
}
```

### Indeterminate

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox } from "@/components/ui/checkbox";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <VStack className="checkbox-preview">
        <Checkbox defaultChecked label="indeterminate" indeterminate tone="neutral" size="large" />
      </VStack>
    </view>
  );
}
```

### Weights

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <VStack className="checkbox-preview">
        <CheckboxGroup>
          <Checkbox label="Regular Label Text" weight="regular" tone="neutral" size="large" />
          <Checkbox label="Bold Label Text" weight="bold" tone="neutral" size="large" />
        </CheckboxGroup>
      </VStack>
    </view>
  );
}
```

### Long Label

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <VStack className="checkbox-preview">
        <CheckboxGroup>
          <Checkbox
            size="medium"
            tone="neutral"
            label="Consequat ut veniam aliqua deserunt occaecat enim occaecat veniam et et cillum nulla officia incididunt incididunt. Sint laboris labore occaecat fugiat culpa voluptate ullamco in elit dolore exercitation nulla."
          />
          <Checkbox
            size="large"
            tone="neutral"
            label="Consequat ut veniam aliqua deserunt occaecat enim occaecat veniam et et cillum nulla officia incididunt incididunt. Sint laboris labore occaecat fugiat culpa voluptate ullamco in elit dolore exercitation nulla."
          />
        </CheckboxGroup>
      </VStack>
    </view>
  );
}
```

### Disabled

```tsx
import "./styles";

import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <VStack className="checkbox-preview">
        <CheckboxGroup>
          <Checkbox
            defaultChecked
            label="Disabled Checked, Square"
            disabled
            tone="neutral"
            size="large"
          />
          <Checkbox
            checked={false}
            label="Disabled without Checked, Square"
            disabled
            tone="neutral"
            size="large"
          />
          <Checkbox
            variant="ghost"
            defaultChecked
            label="Disabled Checked, Ghost"
            disabled
            tone="neutral"
            size="large"
          />
          <Checkbox
            variant="ghost"
            checked={false}
            label="Disabled without Checked, Ghost"
            disabled
            tone="neutral"
            size="large"
          />
        </CheckboxGroup>
      </VStack>
    </view>
  );
}
```

### Listening to Value Changes

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

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox } from "@/components/ui/checkbox";

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

  function handleCheckedChange(checked: boolean) {
    "background only";

    setCount((previous) => previous + 1);
    setLastValue(checked);
  }

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <VStack className="checkbox-preview" gap="x4">
        <Checkbox
          label="Click me"
          tone="neutral"
          size="large"
          onCheckedChange={handleCheckedChange}
        />
        <text className="checkbox-preview__status">
          onCheckedChange called: {count} times, last value:{" "}
          {lastValue === null ? "-" : JSON.stringify(lastValue)}
        </text>
      </VStack>
    </view>
  );
}
```

### Use Cases

#### Using `Checkmark`

Lynx Registry의 `Checkmark`는 자체 `Checkbox.Root`를 포함합니다. 단독으로 사용할 때는 `accessibility-label`을 전달하세요. 문구까지 같은 탭 영역에 넣으려면 Registry `Checkbox`의 `children`을 사용합니다. 이때 `accessibility-label`도 직접 전달하세요.

```tsx
import "./styles";

import { HStack, Text, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox } from "@/components/ui/checkbox";

interface CustomCheckboxProps {
  label: string;
  textStyle: "t7Regular" | "t7Medium" | "t7Bold";
  defaultChecked?: boolean;
}

function CustomCheckbox({ label, textStyle, defaultChecked }: CustomCheckboxProps) {
  return (
    <Checkbox
      accessibility-label={label}
      tone="neutral"
      defaultChecked={defaultChecked}
      style={{ flexDirection: "column", rowGap: "8px", alignItems: "center" }}
    >
      <Text textStyle={textStyle}>{label}</Text>
    </Checkbox>
  );
}

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <HStack className="checkbox-preview" gap="x6">
        <CustomCheckbox label="regular" textStyle="t7Regular" />
        <CustomCheckbox label="medium" textStyle="t7Medium" defaultChecked />
        <CustomCheckbox label="bold" textStyle="t7Bold" />
      </HStack>
    </view>
  );
}
```

### Fieldset Integration

`CheckboxGroup`을 사용하여 여러 체크박스를 그룹화하고 `label`, `description`, `errorMessage` 등의 Fieldset 관련 prop을 사용할 수 있습니다.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { ActionButton, HStack, VStack, useSeedClassName } from "@seed-design/lynx-react";
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox";

export default function Example() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  const [apple, setApple] = useState(true);
  const [banana, setBanana] = useState(false);
  const [orange, setOrange] = useState(false);
  const [firstErrorMessage, setFirstErrorMessage] = useState<string | undefined>();
  const [terms, setTerms] = useState(false);
  const [privacy, setPrivacy] = useState(true);
  const [marketing, setMarketing] = useState(false);
  const [secondErrorMessage, setSecondErrorMessage] = useState<string | undefined>();

  const handleFirstSubmit = () => {
    setFirstErrorMessage(apple ? "Apple은 선택할 수 없습니다." : undefined);
  };

  const handleSecondSubmit = () => {
    setSecondErrorMessage(!terms || !privacy ? "필수 항목에 동의해 주세요." : undefined);
  };

  return (
    <view className={`${seedClassName} docs-lynx-checkbox-root`}>
      <VStack className="checkbox-preview">
        <HStack width="full" gap="x8" align="flex-start">
          <VStack style={{ flex: 1 }} gap="spacingY.componentDefault">
            <CheckboxGroup
              label="좋아하는 과일"
              indicator="선택"
              description="Apple을 선택하고 제출해보세요."
              errorMessage={firstErrorMessage}
            >
              <Checkbox
                label="Apple"
                tone="neutral"
                size="large"
                checked={apple}
                onCheckedChange={setApple}
              />
              <Checkbox
                label="Banana"
                tone="neutral"
                size="large"
                checked={banana}
                onCheckedChange={setBanana}
              />
              <Checkbox
                label="Orange"
                tone="neutral"
                size="large"
                checked={orange}
                onCheckedChange={setOrange}
              />
            </CheckboxGroup>
            <ActionButton variant="neutralSolid" bindtap={handleFirstSubmit}>
              제출
            </ActionButton>
          </VStack>

          <VStack style={{ flex: 1 }} gap="spacingY.componentDefault">
            <CheckboxGroup
              label="약관 동의"
              labelWeight="bold"
              showRequiredIndicator
              description="이용약관을 선택하지 않고 제출해보세요."
              errorMessage={secondErrorMessage}
            >
              <Checkbox
                label="이용약관 동의 (필수)"
                tone="neutral"
                size="large"
                checked={terms}
                onCheckedChange={setTerms}
              />
              <Checkbox
                label="개인정보 처리방침 동의 (필수)"
                tone="neutral"
                size="large"
                checked={privacy}
                onCheckedChange={setPrivacy}
              />
              <Checkbox
                label="마케팅 수신 동의 (선택)"
                tone="neutral"
                size="large"
                checked={marketing}
                onCheckedChange={setMarketing}
              />
            </CheckboxGroup>
            <ActionButton variant="neutralSolid" bindtap={handleSecondSubmit}>
              제출
            </ActionButton>
          </VStack>
        </HStack>
      </VStack>
    </view>
  );
}
```

## 웹 버전과의 차이

<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 범위 밖입니다.
  - **오류 안내 렌더링**: React는 오류가 표시될 때 `description`을 접근성 트리에 남기지만, Lynx에는 DOM의 visually hidden 처리 방식이 없어 화면과 접근성 트리에서 `description`을 제외하고 `errorMessage`만 렌더링합니다.
  - **이벤트 핸들링**: `onChange` 대신 `onCheckedChange`만 노출합니다. tap 핸들러는 Root 내부에서 소유합니다.
  - **Pressed 상태**: 웹의 `data-active` 대신 내부 press state를 `checkmark` recipe의 `pressed` boolean variant로 전달합니다.
  - **Scale Feedback**: Lynx는 눌림 상태를 색상으로 표현하며 React의 `--seed-checkmark-feedback-scale` CSS 변수는 제공하지 않습니다.
  - **접근성 속성**: HTML `<label>` / `<input>` 대신 네이티브 `<view>` / `<text>` 요소를 렌더링합니다. `Checkbox.Root`는 `accessibility-element`, `accessibility-role-description`, `accessibility-value`로 역할과 선택 상태를 전달합니다.
  - **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을 렌더링하지 않음           |
| 개별 `Checkbox`의 `name` / `value` / `required` / `invalid` | form field props           | Lynx에 native form 제출 모델 없음                     |
| React Hook Form 예제                                       | HTML form과 hidden input 연동 | 앱 상태와 `checked` / `onCheckedChange`를 직접 연결해야 함 |
| `focus` / `focusVisible`                                 | 키보드 포커스                    | Lynx에 키보드 포커스 개념 없음                            |
| `onChange` (raw DOM event)                               | `React.ChangeEvent`        | 의미 없음. `onCheckedChange`로 대체                   |
| `weight="default"` / `"stronger"`                        | deprecated 호환 매핑           | Lynx는 `"regular"` / `"bold"`만 노출               |