Skip to content

RadioGroup

A radio group. Compose options with RadioGroup.Item. Inside a Field it takes its id (the field’s controlId), disabled, required, state, aria-labelledby, and aria-describedby from there. An error state sets aria-invalid and colors the items’ default icons. See Field for pairing it with a Hint.

Built on bits-ui RadioGroup.

Focus never lands on the group <div>, and focus and blur do not bubble. To observe focus, set onfocusin and onfocusout on RadioGroup, or onfocus and onblur on an item.

<Field class="flex flex-col gap-1">
<Label>Size</Label>
<RadioGroup bind:value name="size">
<RadioGroup.Item value="sm">Small</RadioGroup.Item>
<RadioGroup.Item value="md">Medium</RadioGroup.Item>
</RadioGroup>
</Field>
<RadioGroup
  value="md"
  orientation="vertical"
  disabled={false}
/>
  • One value for the whole group, bindable, with each RadioGroup.Item naming the value it selects.
  • Roving focus and arrow-key navigation from the WAI-ARIA radio group pattern, via bits-ui.
  • Vertical by default, horizontal with orientation.
  • Takes state from an enclosing Field, or directly. error sets aria-invalid="true" on the role="radiogroup" root and turns each item’s default icon red.
  • Submits with the form through a hidden <input> when given a name.
<RadioGroup>
<RadioGroup.Item value="…">label</RadioGroup.Item>
<RadioGroup.Item value="…">label</RadioGroup.Item>
</RadioGroup>

bind:value on the group. The items need no binding of their own.

value: md

Code
TwoWay.svelte
<script lang="ts">
import { Field, Label, RadioGroup } from "@viamrobotics/prime-ui";
let size = $state("md");
</script>
<div class="not-content">
<Field class="flex flex-col gap-1">
<Label>Size</Label>
<RadioGroup bind:value={size} name="size">
<RadioGroup.Item value="sm">Small</RadioGroup.Item>
<RadioGroup.Item value="md">Medium</RadioGroup.Item>
<RadioGroup.Item value="lg">Large</RadioGroup.Item>
</RadioGroup>
</Field>
<p class="mt-3 text-sm text-subtle-2">value: <code>{size}</code></p>
</div>

Pass bind:value a getter and a setter. State & binding explains both modes.

Enterprise is declined by the setter, so picking it changes nothing.

value: free

Code
Controlled.svelte
<script lang="ts">
import { Field, Hint, Label, RadioGroup } from "@viamrobotics/prime-ui";
let plan = $state("free");
</script>
<div class="not-content">
<Field class="flex flex-col gap-1">
<Label>Plan</Label>
<RadioGroup
name="plan"
bind:value={
() => plan,
(next) => {
if (next !== "enterprise") plan = next;
}
}
>
<RadioGroup.Item value="free">Free</RadioGroup.Item>
<RadioGroup.Item value="team">Team</RadioGroup.Item>
<RadioGroup.Item value="enterprise">Enterprise</RadioGroup.Item>
</RadioGroup>
<Hint>Enterprise is declined by the setter, so picking it changes nothing.</Hint>
</Field>
<p class="mt-3 text-sm text-subtle-2">value: <code>{plan}</code></p>
</div>

Pass an indicator snippet to an item to replace the radio icon. It receives checked. The item’s children stay the label.

Code
CustomIndicator.svelte
<script lang="ts">
import { mdiCheckCircle, mdiCircleMedium } from "@mdi/js";
import { Icon, RadioGroup } from "@viamrobotics/prime-ui";
let value = $state("grid");
</script>
<RadioGroup bind:value orientation="horizontal" class="not-content gap-4" aria-label="Layout">
{#each ["grid", "list", "table"] as layout (layout)}
<RadioGroup.Item value={layout} class="capitalize">
{#snippet indicator({ checked })}
<Icon
icon={checked ? mdiCheckCircle : mdiCircleMedium}
size="lg"
class={checked ? "text-info-dark" : "text-subtle-2"}
/>
{/snippet}
{layout}
</RadioGroup.Item>
{/each}
</RadioGroup>

Pass description to show a line of text under an item’s label. The radio’s accessible description reads it. Pass a details snippet for content that renders only while that item is checked, such as a field the choice needs. An item with either becomes a wrapper <div> holding the button, and class lands on that wrapper. Both sit outside the button, so they stay out of its accessible name and details can hold interactive controls.

We send a sign-in code.

Standard rates apply.

Code
DescriptionDetails.svelte
<script lang="ts">
import { Input, RadioGroup } from "@viamrobotics/prime-ui";
let contact = $state("email");
</script>
<RadioGroup bind:value={contact} class="not-content gap-3" aria-label="Contact method">
<RadioGroup.Item value="email" description="We send a sign-in code.">
{#snippet details()}
<Input type="email" aria-label="Email address" placeholder="you@example.com" />
{/snippet}
Email
</RadioGroup.Item>
<RadioGroup.Item value="sms" description="Standard rates apply.">
{#snippet details()}
<Input type="tel" aria-label="Phone number" placeholder="555 0100" />
{/snippet}
Text message
</RadioGroup.Item>
<RadioGroup.Item value="none">No contact</RadioGroup.Item>
</RadioGroup>

Horizontal

Disabled group

Error

One disabled item

class on RadioGroup lands on the group <div>, which is flex with flex-col or flex-row by orientation, so add the gap you want. class on RadioGroup.Item lands on the item button, or on the wrapper <div> when the item has a description or details. bits-ui sets these data attributes for Tailwind variants.

Element Attribute Value
group data-orientation vertical or horizontal
group data-disabled present when disabled
group aria-invalid true when state is error
item data-state checked or unchecked
item data-value the item’s value
item data-disabled present when disabled
item data-orientation vertical or horizontal

Focus moves between items, and moving focus with the arrow keys also selects the newly focused item.

KeyAction
TabFocuses the checked item, or the first if none is.
ArrowDown / ArrowRightMoves to and selects the next item, wrapping around.
ArrowUp / ArrowLeftMoves to and selects the previous item, wrapping.
Home / EndMoves to and selects the first or last item.
SpaceSelects the focused item.

Each RadioGroup.Item is a real <button>, so onfocus, onblur, onclick, and onkeydown on an item land on it. For the whole group, use onfocusin and onfocusout on RadioGroup, as on a native <fieldset>. The reason is in State & binding.

<RadioGroup bind:value onfocusout={() => (touched = true)}>

No change event fires, since no native control changes. React to the value with $effect or a function binding, as described in State & binding.

PropTypeDefaultDescription
bind:valuestringThe selected value. Two-way bindable.
orientation'vertical' | 'horizontal''vertical'Direction the items are laid out.
namestringName for form submission.
disabledbooleanDisable all options. Defaults to the enclosing field's disabled.
requiredbooleanMake selection required. Defaults to the enclosing field's required.
stateFieldStateContextual state. Defaults to the enclosing field's state.

Plus everything in Omit<HTMLAttributes<HTMLDivElement>, 'onchange'>, spread onto the element.

RadioGroup.Item

A single option within a RadioGroup. Its children are the label.

<RadioGroup.Item value="sm">Small</RadioGroup.Item>

Pass an indicator snippet to replace the radio icon:

<script>
import { mdiRadioboxBlank, mdiRadioboxMarked } from '@mdi/js';
</script>
<RadioGroup.Item value="sm">
{#snippet indicator({ checked })}
<Icon icon={checked ? mdiRadioboxMarked : mdiRadioboxBlank} size="lg" />
{/snippet}
Small
</RadioGroup.Item>

Give an item a description to show a line of text under its label, and a details snippet for content that appears under it only while the item is checked. With either, class lands on a wrapper <div> around the item:

<RadioGroup.Item value="email" description="We send a code.">
{#snippet details()}
<Input aria-label="Email address" />
{/snippet}
Email
</RadioGroup.Item>
PropTypeDefaultDescription
valuestringThe value this item selects when chosen.
indicatorSnippet<[{ checked: boolean }]>Replaces the radio icon. Receives { checked }.
descriptionstringText under the label, which the radio's accessible description reads.
detailsSnippetContent under the label, rendered only while this item is checked.

Plus everything in Omit<HTMLButtonAttributes, 'value'>, spread onto the element.