# 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 { root } from "@lynx-js/react";
import { HStack, VStack, useSeedClassName } from "@seed-design/lynx-react";
import {
  CheckSelectBox,
  CheckSelectBoxCheckmark,
  CheckSelectBoxGroup,
  RadioSelectBoxItem,
  RadioSelectBoxRadiomark,
  RadioSelectBoxRoot,
} from "@/components/ui/select-box";

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

  return (
    <page className={seedClassName}>
      <HStack className="select-box-preview" gap="x6" align="flex-start">
        <VStack className="select-box-preview__column">
          <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">
          <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>
    </page>
  );
}

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

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

## 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`

### Radio Select Box

#### `RadioSelectBoxRoot`

#### `RadioSelectBoxItem`

#### `RadioSelectBoxRadiomark`

## Examples

### Customizing Label

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

```tsx
import "./styles";

import { root } from "@lynx-js/react";
import { Badge, HStack, VStack, useSeedClassName } from "@seed-design/lynx-react";
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>
    </>
  );
}

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

  return (
    <page className={seedClassName}>
      <HStack className="select-box-preview" gap="x8" align="flex-start">
        <VStack className="select-box-preview__column">
          <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">
          <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>
    </page>
  );
}

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

### Listening to Value Changes

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

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

```tsx
import "./styles";

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

function Root() {
  const seedClassName = useSeedClassName({ colorMode: "system" });
  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 (
    <page className={seedClassName}>
      <HStack className="select-box-preview" gap="x8" align="center">
        <VStack className="select-box-preview__column" gap="x4" align="center">
          <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">
          <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>
    </page>
  );
}

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

### Grid Layout (Columns)

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

필요한 경우 `layout` prop을 직접 설정하여 개별 항목의 레이아웃을 오버라이드할 수 있습니다.

```tsx
import "./styles";

import IconDiamond from "@karrotmarket/lynx-multicolor-icon/IconDiamond";
import IconIcecreamcone from "@karrotmarket/lynx-multicolor-icon/IconIcecreamcone";
import { root } from "@lynx-js/react";
import { VStack, useSeedClassName } from "@seed-design/lynx-react";
import {
  CheckSelectBox,
  CheckSelectBoxCheckmark,
  CheckSelectBoxGroup,
  RadioSelectBoxItem,
  RadioSelectBoxRadiomark,
  RadioSelectBoxRoot,
} from "@/components/ui/select-box";

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

  return (
    <page className={seedClassName}>
      <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 />}
          />
          <CheckSelectBox
            prefixIcon={<IconIcecreamcone />}
            defaultChecked
            layout="horizontal"
            label="layout=horizontal"
            description="layout을 horizontal로 오버라이드"
            suffix={<CheckSelectBoxCheckmark />}
          />
          <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 />}
          />
          <RadioSelectBoxItem
            value="option3"
            prefixIcon={<IconDiamond />}
            label="layout=horizontal"
            description="layout을 horizontal로 오버라이드"
            layout="horizontal"
            suffix={<RadioSelectBoxRadiomark />}
          />
          <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>
    </page>
  );
}

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

### With Suffix

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

```tsx
import "./styles";

import IconPersonCircleLine from "@karrotmarket/lynx-monochrome-icon/IconPersonCircleLine";
import { root } from "@lynx-js/react";
import { HStack, VStack, useSeedClassName } from "@seed-design/lynx-react";
import {
  CheckSelectBox,
  CheckSelectBoxCheckmark,
  CheckSelectBoxGroup,
  RadioSelectBoxItem,
  RadioSelectBoxRadiomark,
  RadioSelectBoxRoot,
} from "@/components/ui/select-box";

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

  return (
    <page className={seedClassName}>
      <HStack className="select-box-preview" gap="x8" align="flex-start">
        <VStack className="select-box-preview__column">
          <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">
          <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>
    </page>
  );
}

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

### Collapsible Footer

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

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

```tsx
import "./styles";

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

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

  return (
    <page className={seedClassName}>
      <HStack className="select-box-preview" gap="x8" align="flex-start">
        <VStack className="select-box-preview__column">
          <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">
          <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>
    </page>
  );
}

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

## 웹 버전과의 차이

<Callout type="warning">
  Lynx `Select Box`는 React 버전과 다음 차이가 있습니다.

  - **React Hook Form 미지원**: Lynx에는 native form 제출 모델이 없어 React Hook Form 예제를 제공하지 않습니다.
  - **Field wrapper 없음**: React Registry의 Fieldset과 RadioGroupField 연동, field label, description, error message 연결을 제공하지 않습니다.
  - **form 제출 없음**: Hidden input과 `inputProps`, `name`, `required`, `invalid`를 제공하지 않습니다.
  - **키보드 포커스 없음**: 브라우저의 키보드 focus 대신 네이티브 tap과 접근성 탐색을 사용합니다.
  - **접근성**: HTML ARIA 대신 Lynx의 접근성 역할과 선택 값을 사용합니다.
</Callout>