# Select Box
URL: /lynx/components/select-box
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/select-box.mdx

명확한 테두리를 가진 컨테이너를 활용하여, 정의된 목록 중 하나 이상의 옵션을 선택하는 UI 요소입니다.

Lynx Engine 최소 버전: 3.6

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

## Preview

```tsx
import "./styles";

import { HStack, VStack } from "@seed-design/lynx-react";
import {
  CheckSelectBox,
  CheckSelectBoxCheckmark,
  CheckSelectBoxGroup,
  RadioSelectBoxItem,
  RadioSelectBoxRadiomark,
  RadioSelectBoxRoot,
} from "@/components/ui/select-box";

export default function Example() {
  return (
    <HStack className="select-box-preview" gap="x6" align="flex-start">
      <VStack className="select-box-preview__column" grow shrink style={{ flexBasis: 0 }}>
        <CheckSelectBoxGroup accessibility-label="Fruit">
          <CheckSelectBox label="Apple" defaultChecked suffix={<CheckSelectBoxCheckmark />} />
          <CheckSelectBox
            label="Melon"
            description="Elit cupidatat dolore fugiat enim veniam culpa."
            suffix={<CheckSelectBoxCheckmark />}
          />
          <CheckSelectBox label="Mango" suffix={<CheckSelectBoxCheckmark />} />
        </CheckSelectBoxGroup>
      </VStack>

      <VStack className="select-box-preview__column" grow shrink style={{ flexBasis: 0 }}>
        <RadioSelectBoxRoot defaultValue="apple" accessibility-label="Fruit">
          <RadioSelectBoxItem value="apple" label="Apple" suffix={<RadioSelectBoxRadiomark />} />
          <RadioSelectBoxItem
            value="melon"
            label="Melon"
            description="Elit cupidatat dolore fugiat enim veniam culpa."
            suffix={<RadioSelectBoxRadiomark />}
          />
          <RadioSelectBoxItem value="mango" label="Mango" suffix={<RadioSelectBoxRadiomark />} />
        </RadioSelectBoxRoot>
      </VStack>
    </HStack>
  );
}
```

## Installation

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

## Props

### Check Select Box

#### `CheckSelectBoxGroup`

#### `CheckSelectBox`

#### `CheckSelectBoxCheckmark`

고유 prop이 없습니다. `className`, `style`, `children`을 받습니다.

### Radio Select Box

#### `RadioSelectBoxRoot`

`RadioSelectBoxRoot`는 `label`, `description`, `errorMessage`, `invalid`를 지원합니다. `invalid`가 `true`이고 `errorMessage`가 있으면 description 대신 오류 메시지를 표시합니다.

`columns`는 항목의 열 수를 지정합니다. `className`과 `style`은 그룹 바깥의 Root에 적용됩니다.

#### `RadioSelectBoxItem`

#### `RadioSelectBoxRadiomark`

## Examples

### Customizing Label

`label` prop에 여러 요소를 조합한 사용자 정의 콘텐츠를 전달할 수 있습니다.

```tsx
import "./styles";

import { HStack, VStack } from "@seed-design/lynx-react";
import { Badge } from "@/components/ui/badge";
import {
  CheckSelectBox,
  CheckSelectBoxCheckmark,
  CheckSelectBoxGroup,
  RadioSelectBoxItem,
  RadioSelectBoxRadiomark,
  RadioSelectBoxRoot,
} from "@/components/ui/select-box";

function CustomizedLabel() {
  return (
    <>
      <text>Melon</text>
      <Badge tone="brand" variant="solid">
        New
      </Badge>
    </>
  );
}

export default function Example() {
  return (
    <HStack className="select-box-preview" gap="x8" align="flex-start">
      <VStack className="select-box-preview__column" grow shrink style={{ flexBasis: 0 }}>
        <CheckSelectBoxGroup accessibility-label="Fruit">
          <CheckSelectBox label="Apple" defaultChecked suffix={<CheckSelectBoxCheckmark />} />
          <CheckSelectBox
            accessibility-label="Melon New"
            label={<CustomizedLabel />}
            description="Elit cupidatat dolore fugiat enim veniam culpa."
            suffix={<CheckSelectBoxCheckmark />}
          />
          <CheckSelectBox
            label="Mango"
            description="Aliqua ad aute eiusmod eiusmod nulla adipisicing proident ullamco in."
            suffix={<CheckSelectBoxCheckmark />}
          />
        </CheckSelectBoxGroup>
      </VStack>

      <VStack className="select-box-preview__column" grow shrink style={{ flexBasis: 0 }}>
        <RadioSelectBoxRoot defaultValue="apple" accessibility-label="Fruit">
          <RadioSelectBoxItem value="apple" label="Apple" suffix={<RadioSelectBoxRadiomark />} />
          <RadioSelectBoxItem
            value="melon"
            accessibility-label="Melon New"
            label={<CustomizedLabel />}
            description="Elit cupidatat dolore fugiat enim veniam culpa."
            suffix={<RadioSelectBoxRadiomark />}
          />
          <RadioSelectBoxItem
            value="mango"
            label="Mango"
            description="Aliqua ad aute eiusmod eiusmod nulla adipisicing proident ullamco in."
            suffix={<RadioSelectBoxRadiomark />}
          />
        </RadioSelectBoxRoot>
      </VStack>
    </HStack>
  );
}
```

### Listening to Value Changes

`CheckSelectBox`는 `onCheckedChange`를 사용하여 체크박스의 선택 상태 변경을 감지할 수 있습니다.

`RadioSelectBoxRoot`는 `onValueChange`를 사용하여 라디오 버튼의 선택 값 변경을 감지할 수 있습니다.

```tsx
import "./styles";

import { useState } from "@lynx-js/react";
import { HStack, VStack } from "@seed-design/lynx-react";
import {
  CheckSelectBox,
  CheckSelectBoxCheckmark,
  CheckSelectBoxGroup,
  RadioSelectBoxItem,
  RadioSelectBoxRadiomark,
  RadioSelectBoxRoot,
} from "@/components/ui/select-box";

export default function Example() {
  const [checkCount, setCheckCount] = useState(0);
  const [checkLastValue, setCheckLastValue] = useState<boolean | null>(null);
  const [radioCount, setRadioCount] = useState(0);
  const [radioLastValue, setRadioLastValue] = useState<string | null>(null);

  return (
    <HStack className="select-box-preview" gap="x8" align="center">
      <VStack
        className="select-box-preview__column"
        gap="x4"
        align="center"
        grow
        shrink
        style={{ flexBasis: 0 }}
      >
        <CheckSelectBoxGroup accessibility-label="Fruit">
          <CheckSelectBox
            label="Apple"
            suffix={<CheckSelectBoxCheckmark />}
            onCheckedChange={(checked) => {
              setCheckCount((previous) => previous + 1);
              setCheckLastValue(checked);
            }}
          />
        </CheckSelectBoxGroup>
        <text className="select-box-preview__status">
          onCheckedChange called: {checkCount} times, last value:{" "}
          {checkLastValue === null ? "-" : JSON.stringify(checkLastValue)}
        </text>
      </VStack>

      <VStack
        className="select-box-preview__column"
        gap="x4"
        align="center"
        grow
        shrink
        style={{ flexBasis: 0 }}
      >
        <RadioSelectBoxRoot
          defaultValue="apple"
          accessibility-label="Fruit"
          onValueChange={(value) => {
            setRadioCount((previous) => previous + 1);
            setRadioLastValue(value);
          }}
        >
          <RadioSelectBoxItem value="apple" label="Apple" suffix={<RadioSelectBoxRadiomark />} />
          <RadioSelectBoxItem value="banana" label="Banana" suffix={<RadioSelectBoxRadiomark />} />
        </RadioSelectBoxRoot>
        <text className="select-box-preview__status">
          onValueChange called: {radioCount} times, last value: {radioLastValue ?? "-"}
        </text>
      </VStack>
    </HStack>
  );
}
```

### Grid Layout (Columns)

`columns` prop을 사용하여 여러 열로 배치할 수 있습니다. `columns`가 1보다 크면 하위 요소의 `layout`이 자동으로 `"vertical"`로 설정됩니다.

가로형(`layout="horizontal"`)은 단일 컬럼으로 배치합니다. 여러 열로 구성한 그룹에서 개별 항목을 가로형으로 바꾸려면, 아래 예제처럼 래퍼가 모든 열을 차지하도록 `gridColumnStart`와 `gridColumnEnd`를 지정해 전체 너비를 확보하세요.

래퍼는 `HStack align="stretch"`로 구성해 내부 Select Box가 grid 행 높이를 채우도록 합니다.

```tsx
import "./styles";

import IconDiamond from "@karrotmarket/lynx-multicolor-icon/IconDiamond";
import IconIcecreamcone from "@karrotmarket/lynx-multicolor-icon/IconIcecreamcone";

import { HStack, VStack } from "@seed-design/lynx-react";
import {
  CheckSelectBox,
  CheckSelectBoxCheckmark,
  CheckSelectBoxGroup,
  RadioSelectBoxItem,
  RadioSelectBoxRadiomark,
  RadioSelectBoxRoot,
} from "@/components/ui/select-box";

export default function Example() {
  return (
    <VStack className="select-box-preview" gap="x8">
      <CheckSelectBoxGroup columns={2} accessibility-label="Grid 레이아웃 예제">
        <CheckSelectBox
          prefixIcon={<IconIcecreamcone />}
          label="옵션 1"
          description="layout=vertical"
          suffix={<CheckSelectBoxCheckmark />}
        />
        <CheckSelectBox
          prefixIcon={<IconIcecreamcone />}
          label="옵션 2"
          description="layout=vertical"
          suffix={<CheckSelectBoxCheckmark />}
        />
        <HStack align="stretch" style={{ gridColumnStart: "1", gridColumnEnd: "3" }}>
          <CheckSelectBox
            prefixIcon={<IconIcecreamcone />}
            defaultChecked
            layout="horizontal"
            label="layout=horizontal"
            description="layout을 horizontal로 오버라이드"
            suffix={<CheckSelectBoxCheckmark />}
          />
        </HStack>
        <CheckSelectBox
          prefixIcon={<IconIcecreamcone />}
          label="옵션 4"
          description="layout=vertical"
          suffix={<CheckSelectBoxCheckmark />}
        />
      </CheckSelectBoxGroup>

      <RadioSelectBoxRoot
        columns={3}
        defaultValue="option3"
        accessibility-label="Grid 레이아웃 예제"
      >
        <RadioSelectBoxItem
          value="option1"
          prefixIcon={<IconDiamond />}
          label="옵션 1"
          suffix={<RadioSelectBoxRadiomark />}
        />
        <RadioSelectBoxItem
          value="option2"
          prefixIcon={<IconDiamond />}
          label="옵션 2"
          suffix={<RadioSelectBoxRadiomark />}
        />
        <HStack align="stretch" style={{ gridColumnStart: "1", gridColumnEnd: "4" }}>
          <RadioSelectBoxItem
            value="option3"
            prefixIcon={<IconDiamond />}
            label="layout=horizontal"
            description="layout을 horizontal로 오버라이드"
            layout="horizontal"
            suffix={<RadioSelectBoxRadiomark />}
          />
        </HStack>
        <RadioSelectBoxItem
          value="option4"
          prefixIcon={<IconDiamond />}
          label="옵션 4"
          suffix={<RadioSelectBoxRadiomark />}
        />
        <RadioSelectBoxItem
          value="option5"
          prefixIcon={<IconDiamond />}
          label="옵션 5"
          suffix={<RadioSelectBoxRadiomark />}
        />
        <RadioSelectBoxItem
          value="option6"
          prefixIcon={<IconDiamond />}
          label="옵션 6"
          suffix={<RadioSelectBoxRadiomark />}
        />
      </RadioSelectBoxRoot>
    </VStack>
  );
}
```

### With Suffix

`suffix` prop을 사용하여 체크마크, 라디오 마크, 또는 커스텀 요소를 표시할 수 있습니다. `CheckSelectBoxCheckmark`와 `RadioSelectBoxRadiomark`를 사용하거나, 아이콘이나 텍스트 등 자유로운 요소를 전달할 수 있습니다.

```tsx
import "./styles";

import IconPersonCircleLine from "@karrotmarket/lynx-monochrome-icon/IconPersonCircleLine";

import { HStack, VStack } from "@seed-design/lynx-react";
import {
  CheckSelectBox,
  CheckSelectBoxCheckmark,
  CheckSelectBoxGroup,
  RadioSelectBoxItem,
  RadioSelectBoxRadiomark,
  RadioSelectBoxRoot,
} from "@/components/ui/select-box";

export default function Example() {
  return (
    <HStack className="select-box-preview" gap="x8" align="flex-start">
      <VStack className="select-box-preview__column" grow shrink style={{ flexBasis: 0 }}>
        <CheckSelectBoxGroup accessibility-label="Suffix 예제">
          <CheckSelectBox label="체크마크" suffix={<CheckSelectBoxCheckmark />} />
          <CheckSelectBox
            label="텍스트 suffix"
            suffix={<text className="select-box-preview__suffix">+1,000원</text>}
          />
          <CheckSelectBox
            label="suffix 없음"
            description="Commodo aliquip fugiat aute irure."
            prefixIcon={<IconPersonCircleLine />}
          />
        </CheckSelectBoxGroup>
      </VStack>

      <VStack className="select-box-preview__column" grow shrink style={{ flexBasis: 0 }}>
        <RadioSelectBoxRoot defaultValue="radiomark" accessibility-label="Radiomark 예제">
          <RadioSelectBoxItem
            value="radiomark"
            label="라디오 마크"
            suffix={<RadioSelectBoxRadiomark />}
          />
          <RadioSelectBoxItem
            value="text"
            label="텍스트 suffix"
            description="Commodo aliquip fugiat aute irure."
            suffix={<text className="select-box-preview__suffix">+1,000원</text>}
          />
          <RadioSelectBoxItem
            value="none"
            label="suffix 없음"
            prefixIcon={<IconPersonCircleLine />}
          />
        </RadioSelectBoxRoot>
      </VStack>
    </HStack>
  );
}
```

### Collapsible Footer

`footer` prop으로 추가 콘텐츠를 표시할 수 있습니다. `footerVisibility` prop으로 footer의 표시 조건을 제어할 수 있습니다.

- `"when-selected"` (기본값): 항목이 선택되었을 때만 표시
- `"when-not-selected"`: 항목이 선택되지 않았을 때만 표시
- `"always"`: 항상 표시

```tsx
import "./styles";

import { HStack, VStack } from "@seed-design/lynx-react";
import {
  CheckSelectBox,
  CheckSelectBoxCheckmark,
  CheckSelectBoxGroup,
  RadioSelectBoxItem,
  RadioSelectBoxRadiomark,
  RadioSelectBoxRoot,
} from "@/components/ui/select-box";

export default function Example() {
  return (
    <HStack className="select-box-preview" gap="x8" align="flex-start">
      <VStack className="select-box-preview__column" grow shrink style={{ flexBasis: 0 }}>
        <CheckSelectBoxGroup accessibility-label="Footer 예제">
          <CheckSelectBox
            label="선택 시에만 표시 (기본값)"
            description="footerVisibility='when-selected'"
            suffix={<CheckSelectBoxCheckmark />}
            footer={<text className="select-box-preview__footer">선택되었을 때만 보입니다.</text>}
          />
          <CheckSelectBox
            label="항상 표시"
            description="footerVisibility='always'"
            suffix={<CheckSelectBoxCheckmark />}
            footerVisibility="always"
            footer={<text className="select-box-preview__footer">항상 보입니다.</text>}
          />
          <CheckSelectBox
            label="미선택 시에만 표시"
            description="footerVisibility='when-not-selected'"
            suffix={<CheckSelectBoxCheckmark />}
            footerVisibility="when-not-selected"
            footer={
              <text className="select-box-preview__footer">선택되지 않았을 때만 보입니다.</text>
            }
          />
        </CheckSelectBoxGroup>
      </VStack>

      <VStack className="select-box-preview__column" grow shrink style={{ flexBasis: 0 }}>
        <RadioSelectBoxRoot defaultValue="when-selected" accessibility-label="Footer 예제">
          <RadioSelectBoxItem
            value="when-selected"
            label="선택 시에만 표시 (기본값)"
            description="footerVisibility='when-selected'"
            suffix={<RadioSelectBoxRadiomark />}
            footer={<text className="select-box-preview__footer">선택되었을 때만 보입니다.</text>}
          />
          <RadioSelectBoxItem
            value="always"
            label="항상 표시"
            description="footerVisibility='always'"
            suffix={<RadioSelectBoxRadiomark />}
            footerVisibility="always"
            footer={<text className="select-box-preview__footer">항상 보입니다.</text>}
          />
          <RadioSelectBoxItem
            value="when-not-selected"
            label="미선택 시에만 표시"
            description="footerVisibility='when-not-selected'"
            suffix={<RadioSelectBoxRadiomark />}
            footerVisibility="when-not-selected"
            footer={
              <text className="select-box-preview__footer">선택되지 않았을 때만 보입니다.</text>
            }
          />
        </RadioSelectBoxRoot>
      </VStack>
    </HStack>
  );
}
```

## 웹 버전과의 차이

- Lynx에는 native form 제출 모델이 없어 React Hook Form, hidden input, `name`, `required`를 제공하지 않습니다. 선택 값과 오류 상태를 앱에서 관리하세요.
- 라디오 그룹은 label, description, error message를 지원합니다. 체크박스 그룹은 React Registry의 Fieldset 연동을 제공하지 않습니다.
- 브라우저 키보드 focus 대신 native tap과 접근성 탐색을 사용합니다.
- 각 항목은 독립된 접근성 요소입니다. raw `<text>`를 포함하거나 텍스트가 없는 항목에는 `accessibility-label`을 지정하세요.