Forms

RadioGroup

A group of radio buttons for single selection. Supports list/card variants, horizontal/vertical orientation, legend, descriptions, and controlled state.

Updated in v2.9.0

aria-* props now land on the radio group element instead of the wrapper around it, so an aria-label names the control. class, style and data-* stay on the wrapper. A selector or test query that reached the control through the wrapper needs the change below.

Migration

/* Before 2.9.0: the attribute sat on the wrapper */
[aria-label="Plan"] [role="radiogroup"] {
  outline-offset: 4px;
}

/* From 2.9.0: it is on the control. In a test,
   getByRole('radiogroup', { name: 'Plan' }) now finds it */
[role="radiogroup"][aria-label="Plan"] {
  outline-offset: 4px;
}

Playground

Experiment with different props in real-time.

Choose plan

Starter

Standard

Premium

Variant

Color

Size

Orientation

Disabled

Basic Usage

Pass items and use bind:value.

Starter

Standard

Premium

<script lang="ts">
  import { RadioGroup } from 'sv5ui';

  let plan = $state('standard');

  const plans = [
    { value: 'starter', label: 'Starter' },
    { value: 'standard', label: 'Standard' },
    { value: 'premium', label: 'Premium' }
  ];
</script>

<RadioGroup items={plans} bind:value={plan} />

With Descriptions

Add per-item descriptions.

Express

Delivered within 1-2 business days

Standard

Delivered within 3-5 business days

Economy

Delivered within 7-10 business days

<RadioGroup items={[
  { value: 'express', label: 'Express', description: 'Delivered within 1-2 business days' },
  { value: 'standard', label: 'Standard', description: 'Delivered within 3-5 business days' },
  { value: 'economy', label: 'Economy', description: 'Delivered within 7-10 business days' }
]} bind:value />

Variants

2 visual styles.

List

Starter

Standard

Premium

Card

Starter

Standard

Premium

<!-- List variant (default) -->
<RadioGroup variant="list" legend="List" {items} bind:value />

<!-- Card variant -->
<RadioGroup variant="card" legend="Card" {items} bind:value />

Indicator Position

Control where the radio indicator appears.

Start

Starter

Standard

Premium

End

Starter

Standard

Premium

Hidden

Starter

Standard

Premium

<RadioGroup indicator="start" legend="Start" {items} bind:value />
<RadioGroup indicator="end" legend="End" {items} bind:value />
<RadioGroup indicator="hidden" legend="Hidden" {items} bind:value />

Orientation

Vertical or horizontal layout.

Vertical

Starter

Standard

Premium

Horizontal

Starter

Standard

Premium

<!-- Vertical (default) -->
<RadioGroup orientation="vertical" {items} bind:value />

<!-- Horizontal -->
<RadioGroup orientation="horizontal" {items} bind:value />

Sizes

5 sizes.

Starter

Standard

Premium

Starter

Standard

Premium

Starter

Standard

Premium

Starter

Standard

Premium

Starter

Standard

Premium

<RadioGroup size="xs" {items} bind:value />
<RadioGroup size="sm" {items} bind:value />
<RadioGroup size="md" {items} bind:value />
<RadioGroup size="lg" {items} bind:value />
<RadioGroup size="xl" {items} bind:value />

Colors

8 semantic color schemes.

Primary

Starter

Standard

Premium

Success

Starter

Standard

Premium

Warning

Starter

Standard

Premium

Error

Starter

Standard

Premium

<RadioGroup color="primary" {items} bind:value />
<RadioGroup color="success" {items} bind:value />
<RadioGroup color="warning" {items} bind:value />
<RadioGroup color="error" {items} bind:value />

Legend

Add an accessible legend with legend and required.

Choose your plan

Starter

Standard

Premium

<RadioGroup items={plans} bind:value legend="Choose your plan" required />

Disabled

Disable entire group or individual items.

All disabled

Starter

Standard

Premium

Individual disabled

Free

Pro

Enterprise

<!-- Disable entire group -->
<RadioGroup disabled {items} bind:value />

<!-- Disable individual items -->
<RadioGroup items={[
  { value: 'free', label: 'Free' },
  { value: 'pro', label: 'Pro' },
  { value: 'enterprise', label: 'Enterprise', disabled: true }
]} bind:value />

Loading

Show spinner state.

Starter

Standard

Premium

<RadioGroup loading {items} bind:value />

Card Grid

Combine card variant with horizontal orientation.

Select a plan

Free

5GB storage, basic features

Pro

50GB storage, advanced analytics

Team

Unlimited storage, collaboration

<RadioGroup
  variant="card"
  orientation="horizontal"
  legend="Select a plan"
  items={[
    { value: 'free', label: 'Free', description: '5GB storage, basic features' },
    { value: 'pro', label: 'Pro', description: '50GB storage, advanced analytics' },
    { value: 'team', label: 'Team', description: 'Unlimited storage, collaboration' }
  ]}
  bind:value
/>

Controlled

Use bind:value for two-way binding.

Starter

Standard

Premium

Selected: standard

<script lang="ts">
  import { RadioGroup } from 'sv5ui';

  let value = $state('standard');
</script>

<RadioGroup {items} bind:value />
<p>Selected: {value}</p>

Accessibility

A group with a legend is named by it. Without one, pass aria-label. It lands on the radio group element, where assistive technology looks for it, along with the other naming and describing attributes: aria-label, aria-labelledby, aria-describedby, aria-invalid, aria-required, aria-errormessage and aria-details. class, style, data-* and aria-hidden stay on the wrapper.

Free

Pro

Team

<!-- No legend: name the group yourself -->
<RadioGroup aria-label="Plan" items={plans} value="pro" orientation="horizontal" />

onfocus and onblur describe the group as a whole: each runs once, when focus enters the group and when it leaves, not on every move between options. Inside a FormField the field label names a group that has no legend, and the description is announced.

UI Slots

Use the ui prop to override classes on internal elements.

Slot	Description
`root`	`Outermost wrapper`
`fieldset`	`Fieldset wrapping the group`
`legend`	`Legend element for the fieldset`
`item`	`Each radio item row`
`base`	`The radio circle element`
`container`	`Wrapper around the radio indicator`
`indicator`	`Inner dot when selected`
`loadingIcon`	`Loading spinner icon`
`wrapper`	`Wraps label and description`
`label`	`Label text`
`description`	`Description text`

Snippets

Snippet	Description
`legendSlot`	`Custom legend rendering`
`labelSlot`	`Custom label for each item`
`descriptionSlot`	`Custom description for each item`

Props

Prop	Type	Default	Description
`items`	`RadioGroupItem[]`	`[]`	`Array of radio options`
`value`	`string`	`''`	`Selected value (bindable)`
`onValueChange`	`(value) => void`	`-`	`Callback on selection change`
`variant`	`'list' \| 'card'`	`'list'`	`Visual style`
`indicator`	`'start' \| 'end' \| 'hidden'`	`'start'`	`Indicator position`
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	`Layout direction`
`color`	`ColorType`	`'primary'`	`Color scheme`
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	`Radio size`
`legend`	`string`	`-`	`Fieldset legend text`
`loading`	`boolean`	`false`	`Show loading state`
`disabled`	`boolean`	`false`	`Disable entire group`
`required`	`boolean`	`false`	`Required for form validation`
`loop`	`boolean`	`true`	`Keyboard navigation looping`
`name`	`string`	`-`	`HTML name for form submission`
`id`	`string`	`-`	`HTML id attribute`
`ref`	`HTMLElement \| null`	`null`	`Bindable reference`
`class`	`string`	`-`	`Additional CSS classes`
`ui`	`Record<Slot, Class>`	`-`	`Override slot classes`

Item Props

Prop	Type	Default	Description
`value`	`string`	`-`	`Unique value (required)`
`label`	`string`	`-`	`Display label`
`description`	`string`	`-`	`Description below label`
`disabled`	`boolean`	`false`	`Disable this item`

InputTags Rating