RadioGroup

사용자가 여러 옵션 중 하나만 선택할 수 있게 하는 라디오 그룹 컴포넌트입니다.

Installation

npx @seed-design/cli add ui:radio-group

Usage

설치한 snippet은 기본 사용 경로인 RadioGroup과 RadioGroupItem, 커스텀 레이아웃에서 item context 안의 마크만 조합할 때 쓰는 Radiomark를 함께 export 합니다.

import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";

export function App() {
  return (
    <RadioGroup defaultValue="small">
      <RadioGroupItem value="small" label="Small" />
      <RadioGroupItem value="medium" label="Medium" />
      <RadioGroupItem value="large" label="Large" />
    </RadioGroup>
  );
}

Controlled 모드는 value와 onValueChange를 함께 전달합니다.

import { useState } from "@lynx-js/react";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";

export function ControlledRadioGroup() {
  const [value, setValue] = useState("small");

  return (
    <RadioGroup value={value} onValueChange={setValue}>
      <RadioGroupItem value="small" label="Small" />
      <RadioGroupItem value="medium" label="Medium" />
      <RadioGroupItem value="large" label="Large" />
    </RadioGroup>
  );
}

Disabled

RadioGroup의 disabled prop은 모든 item을 한꺼번에 비활성화합니다. 개별 item에도 disabled를 전달할 수 있고, 둘 중 하나라도 true면 해당 item은 비활성화됩니다.

<RadioGroup defaultValue="small" disabled>
  <RadioGroupItem value="small" label="Small" />
  <RadioGroupItem value="medium" label="Medium" />
</RadioGroup>

<RadioGroup defaultValue="small">
  <RadioGroupItem value="small" label="Small" />
  <RadioGroupItem value="medium" label="Medium" disabled />
</RadioGroup>

Custom Item Content

RadioGroupItem은 label 뒤에 추가 children을 렌더합니다. 라벨 옆에 보조 정보를 붙이는 정도의 커스텀 구성은 snippet API 안에서 처리할 수 있습니다.

import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";

export function CustomRadioGroup() {
  return (
    <RadioGroup defaultValue="regular">
      <RadioGroupItem value="regular" label="Regular">
        <text>기본 두께</text>
      </RadioGroupItem>
      <RadioGroupItem value="bold" label="Bold">
        <text>강한 두께</text>
      </RadioGroupItem>
    </RadioGroup>
  );
}

Props

`RadioGroup`

Prop

Type

value?string | undefined

defaultValue?string | undefined

onValueChange?((value: string) => void) | undefined

style?CSSProperties | undefined

children?React.ReactNode

className?string | undefined

`RadioGroupItem`

Prop

Type

label?React.ReactNode

valuestring

disabled?boolean | undefined

style?CSSProperties | undefined

children?React.ReactNode

className?string | undefined

`Radiomark`

Prop

Type

className?string | undefined

style?CSSProperties | undefined

웹 버전과의 차이

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입니다.

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`로 대체

RadioGroup

Manual Installation

On this page