# React Native Radio Group

> An accessible React Native radio group for iOS, Android and the web: one choice from a few, with descriptions, arrow-key navigation on the web, vertical or horizontal layout, and an iOS check-mark design. Use it as one element with props, or compose the parts.

# RadioGroup

One choice from a few options that are all visible at once. Each option is a `RadioGroupItem`.

```tsx
import { RadioGroup, RadioGroupItem } from 'patine-ui';
```

The quickest way: give `RadioGroup` its `options`, each `{ value, label, description?, disabled? }`.

```tsx live
import { RadioGroup } from 'patine-ui';

export default function Example() {
  return (
    <RadioGroup
      defaultValue="standard"
      aria-label="Shipping"
      options={[
        { value: 'standard', label: 'Standard', description: '4–6 business days' },
        { value: 'express', label: 'Express', description: '1–2 business days' },
        { value: 'pickup', label: 'Pick up in store', disabled: true },
      ]}
    />
  );
}
```

## Compose the parts

For full control, leave `options` out and put a `RadioGroupItem` for each option inside.

```tsx live
import { useState } from 'react';
import { RadioGroup, RadioGroupItem } from 'patine-ui';

export default function Example() {
  const [plan, setPlan] = useState('pro');
  return (
    <RadioGroup value={plan} onValueChange={setPlan} aria-label="Plan">
      <RadioGroupItem value="free" label="Free" description="The core components" />
      <RadioGroupItem value="pro" label="Pro" description="Charts, scheduler and data grid" />
      <RadioGroupItem value="team" label="Team" description="Five seats and priority support" />
    </RadioGroup>
  );
}
```

## Example: choose a plan

Each option's `label` and `description` can be any node, such as a price beside the name. Here the choice also drives the button below it.

```tsx live
import { useState } from 'react';
import { Badge, Button, Card, CardContent, CardFooter, CardHeader, CardTitle, HStack, RadioGroup, RadioGroupItem, Text } from 'patine-ui';

const PLANS = [
  { value: 'monthly', name: 'Monthly', price: '$12', note: 'Billed every month' },
  { value: 'yearly', name: 'Yearly', price: '$99', note: 'Billed once a year', badge: 'Save 31%' },
  { value: 'lifetime', name: 'Lifetime', price: '$249', note: 'Pay once, keep it forever' },
];

export default function Example() {
  const [plan, setPlan] = useState('yearly');
  const chosen = PLANS.find((p) => p.value === plan);
  return (
    <Card style={{ maxWidth: 420, width: '100%' }}>
      <CardHeader>
        <CardTitle>Choose a plan</CardTitle>
      </CardHeader>
      <CardContent>
        <RadioGroup value={plan} onValueChange={setPlan} aria-label="Plan">
          {PLANS.map((p) => (
            <RadioGroupItem
              key={p.value}
              value={p.value}
              label={
                <HStack gap="sm" align="center">
                  <Text weight="medium">{p.name}</Text>
                  <Text color="textSecondary">{p.price}</Text>
                  {p.badge ? <Badge variant="success">{p.badge}</Badge> : null}
                </HStack>
              }
              description={p.note}
              accessibilityLabel={`${p.name}, ${p.price}`}
            />
          ))}
        </RadioGroup>
      </CardContent>
      <CardFooter>
        <Button style={{ flex: 1 }}>{`Continue with ${chosen?.name}`}</Button>
      </CardFooter>
    </Card>
  );
}
```

## Disabled options

`disabled` on an item skips it; on the group it disables them all.

```tsx live
import { RadioGroup, RadioGroupItem } from 'patine-ui';

export default function Example() {
  return (
    <RadioGroup defaultValue="standard" aria-label="Shipping">
      <RadioGroupItem value="standard" label="Standard" description="3 to 5 days" />
      <RadioGroupItem value="express" label="Express" description="Next day" />
      <RadioGroupItem value="pickup" label="Store pickup" description="Not available in your area" disabled />
    </RadioGroup>
  );
}
```

## Horizontal

`orientation="horizontal"` lays short options out in a row, such as a size or a rating scale. The arrow keys still move through them.

```tsx live
import { RadioGroup, Text, VStack } from 'patine-ui';

export default function Example() {
  return (
    <VStack gap="xs">
      <Text weight="medium">Size</Text>
      <RadioGroup
        orientation="horizontal"
        defaultValue="m"
        aria-label="Size"
        options={['XS', 'S', 'M', 'L', 'XL'].map((size) => ({ value: size.toLowerCase(), label: size, disabled: size === 'XS' }))}
      />
    </VStack>
  );
}
```

## Required choice

A radio group doesn't check itself: show an error from your form when nothing is picked, and leave `value` undefined until the user chooses.

```tsx live
import { useState } from 'react';
import { Button, RadioGroup, Text, VStack } from 'patine-ui';

export default function Example() {
  const [reason, setReason] = useState<string>();
  const [tried, setTried] = useState(false);
  return (
    <VStack gap="sm" style={{ maxWidth: 420 }}>
      <Text weight="semibold">Why are you cancelling?</Text>
      <RadioGroup
        value={reason}
        onValueChange={setReason}
        aria-label="Why are you cancelling?"
        options={[
          { value: 'price', label: 'It’s too expensive' },
          { value: 'features', label: 'It’s missing a feature I need' },
          { value: 'switch', label: 'I’m switching to another app' },
          { value: 'other', label: 'Something else' },
        ]}
      />
      {tried && !reason ? <Text size="sm" color="danger">Pick a reason so we can improve.</Text> : null}
      <Button variant="destructive" onPress={() => setTried(true)}>Cancel subscription</Button>
    </VStack>
  );
}
```

## Designs

In the iOS design an option shows a check mark at the end of its row, as in iOS Settings, instead of a circle. The other designs draw a circle with a dot.

```tsx live
import { HStack, RadioGroup, Text, VStack } from 'patine-ui';

const DESIGNS = ['brand', 'ios', 'material', 'web'] as const;
const OPTIONS = [
  { value: 'light', label: 'Light' },
  { value: 'dark', label: 'Dark' },
  { value: 'system', label: 'System' },
];

export default function Example() {
  return (
    <HStack gap="lg" wrap>
      {DESIGNS.map((design) => (
        <VStack key={design} gap="xs" style={{ width: 150 }}>
          <Text size="xs" color="textSecondary">{design}</Text>
          <RadioGroup design={design} defaultValue="dark" aria-label={`Appearance, ${design}`} options={OPTIONS} />
        </VStack>
      ))}
    </HStack>
  );
}
```

## Right to left

```tsx live
import { View } from 'react-native';
import { RadioGroup } from 'patine-ui';

export default function Example() {
  return (
    <View style={{ direction: 'rtl', maxWidth: 360 }}>
      <RadioGroup
        defaultValue="card"
        aria-label="אמצעי תשלום"
        options={[
          { value: 'card', label: 'כרטיס אשראי', description: 'ויזה, מאסטרקארד, אמקס' },
          { value: 'paypal', label: 'PayPal' },
          { value: 'bit', label: 'ביט', disabled: true },
        ]}
      />
    </View>
  );
}
```

## Radio group, segmented control or select?

Use a radio group for two to five options that need a description. Use a [segmented control](./segmented-control) for a few short ones in a row, and a [select](./select) for a long list.

## Accessibility

- The group has the `radiogroup` role and takes `aria-label`. Items are `radio`s with `checked` and `disabled` states.
- On the web, Tab moves into the group to the selected item, and the arrow keys move and select, skipping disabled items.
- Every row is at least 44pt tall, and pressing the label selects too.
- Give the group a name with `aria-label`, or a visible heading it describes: a screen reader reads it when focus enters the group.
- An item with a custom node as its `label` needs an `accessibilityLabel`.

## Props

### RadioGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | The selected item's value, controlled. |
| `defaultValue` | `string` | — | The selected value when uncontrolled. |
| `onValueChange` | `(value: string) => void` | — | Called when the user selects an item. |
| `disabled` | `boolean` | `false` | Disables every item. |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Lays the items out in a column or a row. |
| `options` | `RadioGroupOption[]` | — | Shorthand: `{ value, label, description?, disabled? }` for each option. |
| `children` | `ReactNode` | — | The `RadioGroupItem`s, when you don't give `options`. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |

### RadioGroupItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | **required** | The value it selects. |
| `label` | `ReactNode` | — | Text next to the indicator. |
| `description` | `ReactNode` | — | Secondary text under the label. |
| `disabled` | `boolean` | `false` | Skips this item. |
| `style` | `StyleProp<ViewStyle>` | — | The row. |
| `labelStyle` | `StyleProp<TextStyle>` | — | The label. |
