RadioGroup

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

Edit on GitHubEditllms.txt

iOSAndroid

Preview RadioGroup on your device

Scan with Expo Go

iOS Android

Download Expo Go, then scan the QR code to preview native components.

Installation

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

Usage

Options mode (same API as web)

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 }
];

<RadioGroup
  options={plans}
  value={plan}
  onValueChange={setPlan}
  variant="card"
  columnCount={2}
/>

Compound mode

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

<RadioGroup defaultValue="option1" onValueChange={setSelected}>
  <RadioGroupItem value="option1" label="Option 1" />
  <RadioGroupItem value="option2" label="Option 2" description="With a description" />
  <RadioGroupItem value="option3" label="Option 3" icon="fal star" color="amber" />
</RadioGroup>

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`

RadioGroup

On this page