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
valuefor the whole group, bindable, with eachRadioGroup.Itemnaming 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
statefrom an enclosingField, or directly.errorsetsaria-invalid="true"on therole="radiogroup"root and turns each item’s default icon red. - Submits with the form through a hidden
<input>when given aname.
Anatomy
Section titled “Anatomy”<RadioGroup> <RadioGroup.Item value="…">label</RadioGroup.Item> <RadioGroup.Item value="…">label</RadioGroup.Item></RadioGroup>Two-way binding
Section titled “Two-way binding”bind:value on the group. The items need no binding of their own.
value: md
Code
<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>Fully controlled
Section titled “Fully controlled”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
<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>Custom indicator
Section titled “Custom indicator”Pass an indicator snippet to an item to replace the radio icon. It receives checked. The item’s children stay the label.
Code
<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>Description and details
Section titled “Description and details”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
<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>States
Section titled “States”Horizontal
Disabled group
Error
One disabled item
Styling
Section titled “Styling”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 |
Keyboard
Section titled “Keyboard”Focus moves between items, and moving focus with the arrow keys also selects the newly focused item.
| Key | Action |
|---|---|
| Tab | Focuses the checked item, or the first if none is. |
| ArrowDown / ArrowRight | Moves to and selects the next item, wrapping around. |
| ArrowUp / ArrowLeft | Moves to and selects the previous item, wrapping. |
| Home / End | Moves to and selects the first or last item. |
| Space | Selects the focused item. |
Events
Section titled “Events”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.
| Prop | Type | Default | Description |
|---|---|---|---|
bind:value | string | The selected value. Two-way bindable. | |
orientation | 'vertical' | 'horizontal' | 'vertical' | Direction the items are laid out. |
name | string | Name for form submission. | |
disabled | boolean | Disable all options. Defaults to the enclosing field's disabled. | |
required | boolean | Make selection required. Defaults to the enclosing field's required. | |
state | FieldState | Contextual 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>| Prop | Type | Default | Description |
|---|---|---|---|
value | string | The value this item selects when chosen. | |
indicator | Snippet<[{ checked: boolean }]> | Replaces the radio icon. Receives { checked }. | |
description | string | Text under the label, which the radio's accessible description reads. | |
details | Snippet | Content under the label, rendered only while this item is checked. |
Plus everything in Omit<HTMLButtonAttributes, 'value'>, spread onto the element.