radioGroup
A radio group is a legend and the options under it, exactly one of which is picked. Each option is a control, a label, and sometimes a quieter second line, which is the Checkbox’s anatomy repeated per option.
const items = [
{ value: "weekly", label: "Weekly", description: "One digest on Monday morning." },
{ value: "daily", label: "Daily", description: "One digest a day, at nine." },
];
<RadioGroup legend="Digest" items={items} defaultValue="weekly" />;<script setup lang="ts">
const items = [
{ value: "weekly", label: "Weekly", description: "One digest on Monday morning." },
{ value: "daily", label: "Daily", description: "One digest a day, at nine." },
];
</script>
<template>
<RadioGroup legend="Digest" :items="items" default-value="weekly" />
</template>Reach for it over a set of checkboxes when the options are exclusive and all of them fit on screen. Past about five, a Select is kinder.
The legend earns its keep
legend names the group for a screen reader and heads it on screen. A horizontal group
keeps it for the screen reader and hides it visually, because a legend above a single row
of options reads as a stray line. It is still there, and still read.
One option at a time
Each item carries a value, a label, and optionally a description and disabled.
Disabling one option does not disable the group; disabled on the group itself does.
invalid draws every control in the error color whatever the group’s own color is, which
is the same rule the Checkbox follows.
The dot
The selected control is a filled circle with a smaller one inside it, and that smaller one is a real element reading the control’s state rather than a border trick. Ark’s own example grows the control’s border to five pixels to make the dot, which would mean adding a border color to this library’s safelist for a shape it can already draw.
Selection
React takes value with onValueChange, or defaultValue to leave the choice alone. Vue
takes v-model, with defaultValue as the uncontrolled counterpart.
name and form submit the picked value with the form around the group, or with one
elsewhere on the page.
Slots
The same word names the recipe slot, the data-slot attribute and the key in ui.
- base
- legend
- item
- container
- control
- indicator
- wrapper
- label
- description
Variants
Read off the recipe, so these are the values that actually resolve. A Theme layer can change which one is the default; it cannot add a value.
- color
- primarysecondarysuccessinfowarningerrorneutral
- size
- xssmmdlgxl
Props
Taken by both adapters, read out of the component module. The same names and the same types work in React and Vue.
- ui
RadioGroupUI
Per-slot class overrides.
- color
"primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral"
Defaults to
"primary"- size
"xs" | "sm" | "md" | "lg" | "xl"
Defaults to
"md"- itemsrequired
RadioGroupItem[]
The options to render, in order.
- legend
string
Names the group for a screen reader, and heads it on screen.
- orientation
"horizontal" | "vertical"
Defaults to
"vertical"- disabled
boolean
Disable every option.
- readOnly
boolean
- invalid
boolean
Draw every control in the error color, whatever the group's own color is.
- required
boolean
- name
string
Submits the picked value under this name inside a form.
- form
string
Id of the form to submit with, for a group rendered outside it.
Vue only
Binds v-model.
- class
unknown
- defaultValue
string
- ids
{ root?: string; label?: string; indicator?: string; item?: (value: string) => string; itemLabel?: (value: string) => string; itemControl?: (value: string) => string; itemHiddenInput?: (value: string) => string; }
- #legend
- Overrides the `legend` prop.