# rn-radio-group
URL: /docs/native/components/radio-group

Single-option radio group with an options-driven or compound API, a card variant, icons, colours, descriptions and responsive columns.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-radio-group
```

## Usage

### Options mode (same API as web)

```tsx
import { RadioGroup, type RadioGroupOption } from '@/components/docyrus-native/radio-group';

const plans: RadioGroupOption[] = [
  { value: 'starter', label: 'Starter', description: 'Up to 3 projects', icon: 'fal seedling', color: 'emerald' },
  { value: 'pro', label: 'Pro', description: 'Unlimited projects', icon: 'fal rocket', color: 'indigo-500' },
  { value: 'legacy', label: 'Legacy', disabled: true }
];

```

### Compound mode

```tsx
import { RadioGroup, RadioGroupItem } from '@/components/docyrus-native/radio-group';

```

## API Reference

### RadioGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `RadioGroupOption[]` | — | Options-driven mode (web parity). When set, `children` are ignored |
| `children` | `ReactNode` | — | Compound mode — `RadioGroupItem` elements |
| `value` | `string` | — | Controlled selected value |
| `defaultValue` | `string` | — | Initial value for uncontrolled mode. Ignored when `value` is provided |
| `onValueChange` | `(value: string) => void` | — | Selection change handler |
| `disabled` | `boolean` | `false` | Disable all items |
| `variant` | `'default' \| 'card'` | `'default'` | `card` renders each option as a bordered pressable card with a check indicator |
| `columnCount` | `1 \| 2 \| 3 \| 4 \| 5` | `1` | Grid columns. Collapses to 1 column below 400pt window width and to at most 2 below 768pt (mirrors web `sm:` / `lg:`). Values > 1 override `orientation` |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Radio indicator + label size (native-only) |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction (single-column layout only) |
| `className` | `string` | — | Additional classes for the group container |

### RadioGroupOption

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `value` | `string` | — | Option value (required) |
| `label` | `string` | — | Label text (required) |
| `description` | `string` | — | Secondary text below the label |
| `icon` | `string` | — | DocyrusIcon identifier (e.g. `"fal star"`) |
| `color` | `string` | — | Icon tint, or a colour dot when there is no icon. Tailwind colour name (`"blue"`, `"blue-500"`) or hex |
| `disabled` | `boolean` | `false` | Disable this option |

### RadioGroupItem

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Item value (required) |
| `label` | `string` | — | Label text |
| `description` | `string` | — | Secondary text below the label |
| `icon` | `string` | — | DocyrusIcon identifier |
| `color` | `string` | — | Icon tint / colour dot (Tailwind colour name or hex) |
| `disabled` | `boolean` | `false` | Disable this item |
| `className` | `string` | — | Additional classes for the pressable row / card |
| `labelClassName` | `string` | — | Label classes |

## Components

| Component | Description |
|-----------|-------------|
| `RadioGroup` | Root container — renders `options`, or provides context to `RadioGroupItem` children |
| `RadioGroupItem` | Individual radio (row or card, depending on the group `variant`) |

## Type Exports

| Type | Description |
|------|-------------|
| `RadioGroupProps` | Props for RadioGroup |
| `RadioGroupItemProps` | Props for RadioGroupItem |
| `RadioGroupOption` | Option shape for the `options` mode |
| `RadioGroupSize` | `'sm' \| 'md' \| 'lg'` |
| `RadioGroupOrientation` | `'vertical' \| 'horizontal'` |
| `RadioGroupVariant` | `'default' \| 'card'` |
| `RadioGroupColumnCount` | `1 \| 2 \| 3 \| 4 \| 5` |