Radio

Installation

Barrel

import { Radio, RadioGroup, RadioItem, RadioLegend } from 'kumo-svelte';

Granular

import { Radio, RadioGroup, RadioItem, RadioLegend } from 'kumo-svelte/components/radio';

Usage

<script lang="ts">import { Radio } from "kumo-svelte";</script><Radio.Group legend="Choose an option" defaultValue="a">  <Radio.Item label="Option A" value="a" />  <Radio.Item label="Option B" value="b" /></Radio.Group>

Examples

Default (Vertical)

Radio groups display vertically by default. Each radio has a label displayed to its right.

Horizontal

Use orientation="horizontal" for inline layouts. Items wrap when there isn't enough space.

With Description

Add helper text below the radio items using the description prop.

Control Position

Use controlPosition="end" to place labels before radio buttons.

Radio Card

Use appearance="card" on the group to display each option as a selectable card. Combine with the description prop on each item for richer content.

Radio Card (Control on the Left)

Use controlPosition="start" on a card radio group to place the radio control on the left of the label and description.

Rich Label Content

The label prop on Radio.Item accepts Svelte snippets, so you can embed icons, badges, or other markup alongside the text.

Radio Card (Horizontal)

Combine appearance="card" with orientation="horizontal" for a side-by-side card layout.

With Error

Show validation errors at the group level using the error prop.

Disabled

Disable the entire group or individual items.

Use Radio.Legend with class="sr-only" to keep the legend accessible to screen readers while hiding it visually. This is useful when the radio group is already labeled by a parent Field or heading, and showing the legend would create a redundant label.

Custom Legend Styling

Radio.Legend accepts class for full control over legend presentation. Use it instead of the legend string prop when you need custom typography, colors, or layout.

Typed Values

Use generic values when radio options are numbers, enums, or other non-string values.

API Reference

Radio.Group

Container for radio buttons with legend, description, and error support.

Prop	Type	Default	Description
legend	`string`	-	legend prop.
orientation	`'vertical' \| 'horizontal'`	`"vertical"`	Layout orientation.
appearance	`'default' \| 'card'`	`"default"`	Visual appearance preset.
error	`string`	-	Validation error message or matcher.
description	`string \| Snippet`	-	Supporting description text.
value	`Value`	-	Controlled value. Parameterized by the radio value type Value, which defaults to string.
disabled	`boolean`	`false`	Disables the component.
controlPosition	`'start' \| 'end'`	-	Control position relative to label.
name	`string`	-	Form field name.
defaultValue	`Value`	-	Initial uncontrolled value. Parameterized by the radio value type Value, which defaults to string.
required	`boolean`	-	Marks the field as required.
onValueChange	`(value: Value, eventDetails?: unknown) => void`	-	Called when the value changes. The second argument carries native event details about the interaction.

Radio.Legend

Composable legend sub-component for Radio.Group. Accepts class for full styling control (e.g. class="sr-only" to visually hide). Use instead of the legend string prop when you need custom legend styling.

Prop	Type	Default	Description
No component-specific props. Accepts standard HTML attributes.

Radio.Item

Individual radio button within Radio.Group.

Prop	Type	Default	Description
disabled	`boolean`	`false`	Disables the component.
variant	`'default' \| 'error'`	`"default"`	Visual variant.
appearance	`'default' \| 'card'`	-	Visual appearance preset.
label *	`string \| Snippet`	-	Visible label content.
description	`string \| Snippet`	-	Supporting description text.
value *	`Value`	-	Item value. Parameterized by the radio value type Value to match the enclosing Radio.Group value type.

Accessibility

Semantic HTML

Radio.Group uses semantic <fieldset> and <legend> elements for proper grouping and screen reader announcement.

Keyboard Navigation

Arrow Up/Down or Arrow Left/Right moves between options. Space selects the focused option. Tab moves focus to and from the radio group.

Screen Readers

Each radio is announced with its label and selection state. The group legend provides context for all options.

Kumo Svelte