# RadioGroup
URL: /lynx/components/radio-group
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/radio-group.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 { RadioGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";

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

  return (
    <page className={seedClassName}>
      <VStack className="radio-group-preview">
        <RadioGroup.Root defaultValue="apple" size="large" tone="neutral">
          <RadioGroup.Item value="apple">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>사과</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="banana">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>바나나</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="orange">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>오렌지</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
      </VStack>
    </page>
  );
}

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

## Installation

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

## Props

### `RadioGroup`

### `RadioGroupItem`

### `Radiomark`

## Examples

### Sizes

```tsx
import "./styles";
import { root } from "@lynx-js/react";
import { RadioGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";

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

  return (
    <page className={seedClassName}>
      <VStack className="radio-group-preview" gap="x5">
        <RadioGroup.Root defaultValue="apple" size="medium" tone="neutral">
          <RadioGroup.Item value="apple">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>사과</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="banana">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>바나나</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
        <RadioGroup.Root defaultValue="red" size="large" tone="neutral">
          <RadioGroup.Item value="red">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>빨간색</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="blue">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>파란색</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
      </VStack>
    </page>
  );
}

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

### Tones

#### Brand

```tsx
import "./styles";
import { root } from "@lynx-js/react";
import { RadioGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";

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

  return (
    <page className={seedClassName}>
      <VStack className="radio-group-preview">
        <RadioGroup.Root defaultValue="apple" size="large" tone="brand">
          <RadioGroup.Item value="apple">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>사과</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="banana">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>바나나</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="orange">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>오렌지</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
      </VStack>
    </page>
  );
}

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

#### Neutral

```tsx
import "./styles";
import { root } from "@lynx-js/react";
import { RadioGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";

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

  return (
    <page className={seedClassName}>
      <VStack className="radio-group-preview">
        <RadioGroup.Root defaultValue="apple" size="large" tone="neutral">
          <RadioGroup.Item value="apple">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>사과</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="banana">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>바나나</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="orange">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>오렌지</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
      </VStack>
    </page>
  );
}

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

### Weights

```tsx
import "./styles";
import { root } from "@lynx-js/react";
import { RadioGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";

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

  return (
    <page className={seedClassName}>
      <VStack className="radio-group-preview" gap="x5">
        <RadioGroup.Root defaultValue="regular-1" size="large" tone="neutral" weight="regular">
          <RadioGroup.Item value="regular-1">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>Regular</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="regular-2">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>Regular</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
        <RadioGroup.Root defaultValue="bold-1" size="large" tone="neutral" weight="bold">
          <RadioGroup.Item value="bold-1">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>Bold</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="bold-2">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>Bold</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
      </VStack>
    </page>
  );
}

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

### Long Label

```tsx
import "./styles";
import { root } from "@lynx-js/react";
import { RadioGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";

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

  return (
    <page className={seedClassName}>
      <VStack className="radio-group-preview">
        <RadioGroup.Root defaultValue="medium" size="medium" tone="neutral">
          <RadioGroup.Item value="medium">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>
              긴 라벨도 여러 줄로 자연스럽게 표시되어 선택 항목의 내용을 모두 확인할 수 있습니다.
            </RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="large">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>
              화면 너비가 좁아져도 라디오 마크와 라벨의 정렬을 유지합니다.
            </RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
      </VStack>
    </page>
  );
}

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

### Disabled

`RadioGroup.Root`의 `disabled`는 그룹 전체를 비활성화합니다. 개별 `RadioGroup.Item`도 따로 비활성화할 수 있습니다.

```tsx
import "./styles";
import { root } from "@lynx-js/react";
import { RadioGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";

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

  return (
    <page className={seedClassName}>
      <VStack className="radio-group-preview" gap="x8">
        <RadioGroup.Root defaultValue="option1" size="large" tone="neutral">
          <RadioGroup.Item value="option1">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>활성 옵션</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="option2" disabled>
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>비활성 옵션</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
        <RadioGroup.Root defaultValue="all-disabled" size="large" tone="neutral" disabled>
          <RadioGroup.Item value="all-disabled">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>그룹 전체 비활성</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="unavailable">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>선택할 수 없음</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
      </VStack>
    </page>
  );
}

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

### Listening to Value Changes

`RadioGroup.Root`의 `onValueChange`로 선택 값 변경을 감지할 수 있습니다. Controlled 모드에서는 `value`와 `onValueChange`를 함께 사용합니다.

```tsx
import "./styles";
import { root, useState } from "@lynx-js/react";
import { RadioGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";

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

  return (
    <page className={seedClassName}>
      <VStack className="radio-group-preview" gap="x4">
        <RadioGroup.Root
          defaultValue="apple"
          size="large"
          tone="neutral"
          onValueChange={(value) => {
            setCount((previous) => previous + 1);
            setLastValue(value);
          }}
        >
          <RadioGroup.Item value="apple">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>사과</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="banana">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>바나나</RadioGroup.ItemLabel>
          </RadioGroup.Item>
          <RadioGroup.Item value="orange">
            <RadioGroup.ItemControl>
              <RadioGroup.ItemIndicator />
            </RadioGroup.ItemControl>
            <RadioGroup.ItemLabel>오렌지</RadioGroup.ItemLabel>
          </RadioGroup.Item>
        </RadioGroup.Root>
        <text className="radio-group-preview__status">
          onValueChange 호출: {count}회, 마지막 값: {JSON.stringify(lastValue)}
        </text>
      </VStack>
    </page>
  );
}

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

### Use Cases

#### Using `Radiomark`

`RadioGroup.ItemControl`과 `RadioGroup.ItemIndicator`를 직접 조합하면 선택 상태를 공유하면서 항목의 배치를 바꿀 수 있습니다.

```tsx
import "./styles";
import { root } from "@lynx-js/react";
import { HStack, RadioGroup, VStack, useSeedClassName } from "@seed-design/lynx-react";

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

  return (
    <page className={seedClassName}>
      <VStack className="radio-group-preview">
        <RadioGroup.Root defaultValue="medium" size="large" tone="neutral">
          <HStack gap="x6">
            <RadioGroup.Item value="regular">
              <VStack gap="x2" align="center">
                <RadioGroup.ItemControl>
                  <RadioGroup.ItemIndicator />
                </RadioGroup.ItemControl>
                <RadioGroup.ItemLabel>Regular</RadioGroup.ItemLabel>
              </VStack>
            </RadioGroup.Item>
            <RadioGroup.Item value="medium">
              <VStack gap="x2" align="center">
                <RadioGroup.ItemControl>
                  <RadioGroup.ItemIndicator />
                </RadioGroup.ItemControl>
                <RadioGroup.ItemLabel>Medium</RadioGroup.ItemLabel>
              </VStack>
            </RadioGroup.Item>
            <RadioGroup.Item value="bold">
              <VStack gap="x2" align="center">
                <RadioGroup.ItemControl>
                  <RadioGroup.ItemIndicator />
                </RadioGroup.ItemControl>
                <RadioGroup.ItemLabel>Bold</RadioGroup.ItemLabel>
              </VStack>
            </RadioGroup.Item>
          </HStack>
        </RadioGroup.Root>
      </VStack>
    </page>
  );
}

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

## 웹 버전과의 차이

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

  - **Field wrapper 없음**: React snippet의 `label`, `description`, `errorMessage`, `indicator`, `showRequiredIndicator` 같은 field 관련 prop은 Lynx snippet에서 제공하지 않습니다.
  - **아이콘 렌더링 방식**: 기본 `RadioGroup.ItemIndicator`는 `<view>` dot으로 렌더됩니다. custom icon을 전달할 때는 `@karrotmarket/lynx-monochrome-icon`의 monochrome icon 컴포넌트를 사용해야 하며 raw `<svg>` 주입은 Lynx 범위 밖입니다.
  - **이벤트 핸들링**: `onChange` 대신 `onValueChange(value: string)`만 노출합니다. tap 핸들러는 item 내부에서 소유합니다.
  - **Pressed 상태**: 웹의 `data-active` 대신 내부 press state를 `radiomark` recipe의 `pressed` boolean variant로 전달합니다.
  - **렌더링 요소**: HTML `<label>` / `<input type="radio">` 대신 네이티브 `<view>` / `<text>` 요소를 렌더링합니다.
  - **Strict containment**: `RadioGroupItem`, `Radiomark`, `RadioGroup.ItemControl`, `RadioGroup.ItemIndicator`, `RadioGroup.ItemLabel`은 반드시 `RadioGroup.Root`와 `RadioGroup.Item`의 적절한 context 안에서 사용해야 합니다. `Radiomark`는 standalone primitive가 아니라 item context 안에서 `ItemControl`과 `ItemIndicator`를 묶는 snippet helper입니다.
</Callout>

## Lynx 미지원 기능

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

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

| 기능                                                       | 웹 대응                   | 설명                                      |
| -------------------------------------------------------- | ---------------------- | --------------------------------------- |
| `RadioGroupItemHiddenInput`                              | `<input type="radio">` | Lynx에 HTML form 제출 모델 없음                |
| `name` / `required` / `invalid`                          | form field props       | Lynx에 native form 제출 모델 없음              |
| `inputProps`                                             | 내부 input prop 전달       | Lynx에는 전달할 HTML input이 없음               |
| `label` / `description` / `errorMessage` on `RadioGroup` | field wrapper props    | Lynx에 대응 field wrapper snippet을 제공하지 않음 |
| `focus` / `focusVisible`                                 | 키보드 포커스                | Lynx에 키보드 포커스 개념 없음                     |
| `onChange` (raw DOM event)                               | `React.ChangeEvent`    | 의미 없음. `onValueChange`로 대체              |