Radio Group
updatedYou have no choice. Well, one. A set of radio buttons where exactly one can be selected.
Open Props in the corner of the example to try color, size and disabled. Disable one option with its Field, or the whole group with a FieldSet.
color works as on the checkbox: Button's colours or your own, an --input ring until selected, and red when invalid. Set it on the RadioGroup for every radio, or on one Radio to single it out.
The same scale as the checkbox: xs, 14px, to xl, 24px, with md, 18px, as the default, so radios and checkboxes line up in one form.
Installation
Usage
<script setup lang="ts">
import { Field, FieldLabel } from '@/components/ui/field'
import { Radio, RadioGroup } from '@/components/ui/radio-group'
const density = ref('comfortable')
</script>
<template>
<RadioGroup v-model="density" aria-label="Density">
<Field v-for="option in ['default', 'comfortable', 'compact']" :key="option" orientation="horizontal">
<Radio :value="option" />
<FieldLabel>{{ option }}</FieldLabel>
</Field>
</RadioGroup>
</template>
Works like Checkbox: same sizes, touch targets and group layouts. Here's what's different.
When selected, the ring turns its colour, --primary by default, and a dot grows in from the centre (instantly, with reduced motion).
Unlike checkboxes, the whole group is one Tab stop. Tab lands on the selected radio, or the first one, and arrow keys move the selection.
Examples
Touch target
Smaller than a finger? Add touch-target: expand when it stands alone, wrapper when it sits close to others. How it works.
With wrapper, the label moves along with the radio.
Description
Name the group with a FieldSet and its legend, and give each option a FieldContent for its label and description.
Invalid
Radios are wrong together, not one by one. Put invalid, required and the FieldError on the FieldSet, and the whole group turns red.
Try it: press Continue without picking a size. Reset clears the choice, since a radio can't be unchecked by clicking it again.
API Reference
Both parts accept class, merged over their base classes.
RadioGroup
| Prop | Default | Type and description |
|---|---|---|
| modelValue | — | AcceptableValueThe |
| defaultValue | — | AcceptableValueThe starting value when |
| disabled | — | booleanDisables every radio. Also set by a disabled fieldset. |
| orientation | — | DataOrientation
|
| dir | — | DirectionReading direction for arrow keys. |
| loop | — | booleanWraps arrow-key focus from the last radio to the first. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| name | — | stringSubmits the selected value with its form under this name. |
| required | — | booleanMarks the group required. Also set by a required fieldset. |
| variant | — | "default" | "card" | "list" | "table" | null
|
| color | "primary" | RadioColor | (string & {})Colour role of every radio in the group that has no |
| Event | Payload and description |
|---|---|
| update:modelValue | [payload: AcceptableValue]Fires when another radio is selected. |
| Slot | Scope and description |
|---|---|
| default | {}The radios, usually each in a horizontal |
Radio
| Prop | Default | Type and description |
|---|---|---|
| id | — | stringOverrides the |
| value | — | AcceptableValueThe value the group's |
| disabled | — | booleanDisables this radio. Also set by a disabled field, group or fieldset. |
| name | — | stringSet on the group instead; the group submits the selected value. |
| required | — | booleanSet on the group, or on a surrounding fieldset, instead. |
| color | — | RadioColor | (string & {})Colour role of the ring and dot once selected. Any other name picks up a colour you declare on |
| size | "md" | RadioSizeCircle size, from 14px for |
| touchTarget | — | "none" | "expand" | "wrapper" | nullGrows the pressable area to 48px without changing how the circle looks. |
| Event | Payload and description |
|---|---|
| select | [event: SelectEvent$2]Fires when this radio is selected, with an event whose default can be prevented to keep the selection unchanged. |
Props
- modelValue
AcceptableValueThevalueof the selected radio, bound withv-model.- defaultValue
AcceptableValueThe starting value whenv-modelis not used.- disabled
booleanDisables every radio. Also set by a disabled fieldset.- orientation
DataOrientationhorizontallays the options out in a row, and makes left and right arrows move between them.- dir
DirectionReading direction for arrow keys.- loop
booleanWraps arrow-key focus from the last radio to the first.- asChild
booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- name
stringSubmits the selected value with its form under this name.- required
booleanMarks the group required. Also set by a required fieldset.- variant
"default" | "card" | "list" | "table" | nullcard,listortablerestyle every option in the group, making each whole card or row clickable.- color
"primary" RadioColor | (string & {})Colour role of every radio in the group that has nocolorof its own, and of a selected card's edge or row's tint.
Emits
- update:modelValue
[payload: AcceptableValue]Fires when another radio is selected.
Slots
- default
{}The radios, usually each in a horizontalFieldwith its label.
Props
- id
stringOverrides theidtaken from a surrounding field.- value
AcceptableValueThe value the group'sv-modeltakes when this radio is selected.- disabled
booleanDisables this radio. Also set by a disabled field, group or fieldset.- name
stringSet on the group instead; the group submits the selected value.- required
booleanSet on the group, or on a surrounding fieldset, instead.- color
RadioColor | (string & {})Colour role of the ring and dot once selected. Any other name picks up a colour you declare on[data-slot][data-color="<name>"]. Without one, the radio takes its group'scolor, orprimary. An invalid group turnsdestructivewhatever the colour.- size
"md" RadioSizeCircle size, from 14px forxsto 24px forxl, the same scale as the checkbox.- touchTarget
"none" | "expand" | "wrapper" | nullGrows the pressable area to 48px without changing how the circle looks.wrapperalso reserves that space in layout;expandmay overlap neighbours.
Emits
- select
[event: SelectEvent$2]Fires when this radio is selected, with an event whose default can be prevented to keep the selection unchanged.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| radio-group | data-variant, data-color, data-orientation, data-disabled | The group. |
| radio | data-state, data-color, data-size, data-disabled, data-touch-target | One radio. data-state is checked or unchecked. data-color is its own color, or the group's. |