# Radio Group

> Picks one option from a few that are all visible.

A radio group shows two to five options at once and lets people pick exactly one.

## When to use

- Use it for 2 to 5 options that people should compare before picking, such as the type of a release.
- Use a [Select](https://design.sosialoka.tech/components/select/) for more options, and a [Switch](https://design.sosialoka.tech/components/switch/) or [Checkbox](https://design.sosialoka.tech/components/checkbox/) for one yes-or-no setting.
- Always pick a sensible default.

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/radio-group/_

## Anatomy

1. Option
2. Selected option
3. Label

A `FieldSet` with a `FieldLegend` that asks the question, and one row per option: a round item on an `input` border that fills with `primary` when chosen, its label and an optional one-sentence description.

## Variants

There is one style.

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `value` / `defaultValue` | `v-model` / `default-value` | `initialValue` | text | none | The chosen option. |
| `onValueChange` | `@update:model-value` | `onChanged` | function | none | Runs when the choice changes. |
| `RadioGroupItem value` | `RadioGroupItem value` | `ShadRadio value` | text | none | One option. |
| label in `FieldLabel` | label in `FieldLabel` | `label`, `sublabel` | text | none | Names the option. |
| `disabled` | `disabled` | `enabled: false` | boolean | `false` | Blocks the group or one item. |

## Code

**React**
```tsx
import { useId } from "react"
import { Field, FieldContent, FieldDescription, FieldLabel, FieldLegend, FieldSet } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

const types = [
  { value: "single", label: "Single", hint: "Satu sampai tiga lagu." },
  { value: "ep", label: "EP", hint: "Empat sampai enam lagu." },
  { value: "album", label: "Album", hint: "Tujuh lagu atau lebih." },
]

export default function RadioGroupDemo() {
  const id = useId()
  return (
    <FieldSet className="w-full max-w-sm">
      <FieldLegend id={`${id}-legend`}>Jenis rilis</FieldLegend>
      <RadioGroup defaultValue="single" aria-labelledby={`${id}-legend`}>
        {types.map((t) => (
          <Field key={t.value} orientation="horizontal">
            <RadioGroupItem value={t.value} id={`${id}-${t.value}`} aria-describedby={`${id}-${t.value}-hint`} />
            <FieldContent>
              <FieldLabel htmlFor={`${id}-${t.value}`}>{t.label}</FieldLabel>
              <FieldDescription id={`${id}-${t.value}-hint`}>{t.hint}</FieldDescription>
            </FieldContent>
          </Field>
        ))}
      </RadioGroup>
    </FieldSet>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { useId } from "vue"
import { Field, FieldContent, FieldDescription, FieldLabel, FieldLegend, FieldSet } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

const types = [
  { value: "single", label: "Single", hint: "Satu sampai tiga lagu." },
  { value: "ep", label: "EP", hint: "Empat sampai enam lagu." },
  { value: "album", label: "Album", hint: "Tujuh lagu atau lebih." },
]
const id = useId()
</script>

<template>
  <FieldSet class="w-full max-w-sm">
    <FieldLegend :id="`${id}-legend`">Jenis rilis</FieldLegend>
    <RadioGroup default-value="single" :aria-labelledby="`${id}-legend`">
      <Field v-for="t in types" :key="t.value" orientation="horizontal">
        <RadioGroupItem :id="`${id}-${t.value}`" :value="t.value" :aria-describedby="`${id}-${t.value}-hint`" />
        <FieldContent>
          <FieldLabel :for="`${id}-${t.value}`">{{ t.label }}</FieldLabel>
          <FieldDescription :id="`${id}-${t.value}-hint`">{{ t.hint }}</FieldDescription>
        </FieldContent>
      </Field>
    </RadioGroup>
  </FieldSet>
</template>
```

**Flutter**
```dart
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

const releaseTypes = {
  'single': ('Single', 'Satu sampai tiga lagu.'),
  'ep': ('EP', 'Empat sampai enam lagu.'),
  'album': ('Album', 'Tujuh lagu atau lebih.'),
};

class RadioGroupDemo extends StatelessWidget {
  const RadioGroupDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return Semantics(
      label: 'Jenis rilis',
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.start,
        spacing: 12,
        children: [
          Text('Jenis rilis', style: ShadTheme.of(context).textTheme.small),
          ShadRadioGroup<String>(
            initialValue: 'single',
            items: [
              for (final MapEntry(key: value, value: (label, hint)) in releaseTypes.entries)
                ShadRadio(value: value, label: Text(label), sublabel: Text(hint)),
            ],
          ),
        ],
      ),
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/radio-group.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/radio-group.json
```

## Accessibility

- The group has `role="radiogroup"`, named by its legend; each option has `role="radio"`.
- Tab moves into the group to the chosen option; the arrow keys move the choice.
- Tie each description to its option with `aria-describedby`.
