---
title: "RadioGroup"
description: "A set of mutually exclusive options with one selected value."
category: "Form & Input"
slug: radio-group
url: /components/radio-group
since: "0.1.0"
status: "stable"
---

# RadioGroup

A set of mutually exclusive options with one selected value.

## Import

```svelte
import { RadioGroup } from '@elluzion/iv-ui';
```

## Preview

A vertical list with one selected value.

```svelte
<script lang="ts">
	import { RadioGroup } from '@elluzion/iv-ui';

	let plan = $state('pro');
</script>

<div class="field-row">
	<RadioGroup
		label="Plan"
		items={[
			{ value: 'free', label: 'Free' },
			{ value: 'pro', label: 'Pro' },
			{ value: 'team', label: 'Team' }
		]}
		bind:value={plan}
	/>
	<p class="readout">selected: {plan}</p>
</div>

<style>
	.field-row {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-md);
		width: 100%;
		max-width: 320px;
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

## Usage

- `items` accepts strings or `{ value, label, disabled }`.
- Bind `value`; `onchange` fires with `{ value }` after a selection changes.
- Use `orientation="horizontal"` for compact choice rows.

## Examples

### Horizontal

The same group laid out as a row.

```svelte
<script lang="ts">
	import { RadioGroup } from '@elluzion/iv-ui';

	let cadence = $state('daily');
</script>

<div class="field-row">
	<RadioGroup
		label="Digest cadence"
		orientation="horizontal"
		items={['hourly', 'daily', 'weekly']}
		bind:value={cadence}
	/>
</div>

<style>
	.field-row {
		width: 100%;
		max-width: 420px;
	}
</style>
```

### Disabled

A disabled option and a fully disabled group.

```svelte
<script lang="ts">
	import { RadioGroup } from '@elluzion/iv-ui';

	let plan = $state('pro');
</script>

<div class="field-row">
	<RadioGroup
		label="Plan"
		items={[
			{ value: 'free', label: 'Free' },
			{ value: 'pro', label: 'Pro' },
			{ value: 'enterprise', label: 'Enterprise — sales only', disabled: true }
		]}
		bind:value={plan}
	/>
	<RadioGroup label="Region" items={['eu-west', 'us-east']} value="eu-west" disabled />
</div>

<style>
	.field-row {
		display: flex;
		flex-direction: column;
		gap: var(--iv_spacing-xl);
		width: 100%;
		max-width: 320px;
	}
</style>
```

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` **required** | `RadioItem[]` | `[]` | Radio options. Strings are used as both value and label. |
| `value` **bindable** | `string` | `''` | Selected value. Bind with `bind:value`. |
| `label` | `string` | `''` | Visible label for the control. |
| `name` | `string` | `''` | Shared name for the native radio inputs. |
| `size` | `'sm' \| 'md'` | `'md'` | Control size. |
| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Layout direction. |
| `disabled` | `boolean` | `false` | Disables interaction and applies the disabled treatment. |

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `change` | `(e: CustomEvent<{ value: string }>) => void` | Called with `{ value }` after the selection changes. |

The legacy `on:name` form is accepted for every event.

### Types

#### `RadioItem`

A radio value or a labelled radio option.

```ts
type RadioItem = string | { value: string; label?: string; disabled?: boolean };
```

### Tokens used

`--iv_border` · `--iv_control-md` · `--iv_control-sm` · `--iv_disabled-opacity` · `--iv_ease-out` · `--iv_font-ui` · `--iv_foreground` · `--iv_leading-tight` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_radio-border` · `--iv_radio-dot` · `--iv_radio-dot-sm` · `--iv_spacing-2xs` · `--iv_spacing-sm` · `--iv_spacing-xl` · `--iv_surface-raised` · `--iv_text-body` · `--iv_text-btn-sm` · `--iv_text-label` · `--iv_transition-fast`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-checked` · `.iv-circle` · `.iv-disabled` · `.iv-dot` · `.iv-group-label` · `.iv-horizontal` · `.iv-item` · `.iv-items` · `.iv-label` · `.iv-md` · `.iv-native` · `.iv-root` · `.iv-sm`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus into the group. |
| `Arrow keys` | Move between radios and select the focused one. |
| `Space` | Selects the focused radio. |

- The group is labelled by `label` through `aria-labelledby`.
- Each option is a native radio input inside a `<label>`.
- Only the selected radio is in the tab order, matching native behaviour.

## Related

- [Checkbox](/components/checkbox.md)
- [Switch](/components/switch.md)
- [Select](/components/select.md)
- [Field](/components/field.md)