Radio

A headless radio button component for single-selection groups with keyboard navigation and roving tabindex.

Copy Markdown

Intermediate100% coverageJan 27, 2026

Usage

Radio buttons must be used within a Radio.Group. Use v-model on the group to bind the selected value:

SmallMediumLarge

Selected: none

<script setup lang="ts">
  import { Radio } from '@vuetify/v0'
  import { ref } from 'vue'

  const selected = ref<string>()

  const options = [
    { value: 'small', label: 'Small' },
    { value: 'medium', label: 'Medium' },
    { value: 'large', label: 'Large' },
  ]
</script>

<template>
  <Radio.Group v-model="selected" class="flex flex-col gap-2">
    <label
      v-for="option in options"
      :key="option.value"
      class="inline-flex items-center gap-2"
    >
      <Radio.Root
        class="size-5 border rounded-full inline-flex items-center justify-center border-divider data-[state=checked]:border-primary"
        :value="option.value"
      >
        <Radio.Indicator class="size-2.5 rounded-full bg-primary" />
      </Radio.Root>
      <span>{{ option.label }}</span>
    </label>
  </Radio.Group>

  <p class="mt-4 text-sm text-on-surface-variant">
    Selected: {{ selected || 'none' }}
  </p>
</template>

Anatomy

<script setup lang="ts">
  import { Radio } from '@vuetify/v0'
</script>

<template>
  <Radio.Group>
    <Radio.Root>
      <Radio.Indicator />
    </Radio.Root>

    <Radio.Root>
      <Radio.Indicator />
    </Radio.Root>
  </Radio.Group>

  <!-- With form submission -->
  <Radio.Group>
    <Radio.Root>
      <Radio.Indicator />

      <Radio.HiddenInput />
    </Radio.Root>

    <Radio.Root>
      <Radio.Indicator />

      <Radio.HiddenInput />
    </Radio.Root>
  </Radio.Group>
</template>

Auto-Select First Option

Radio groups are inherently mandatory—once a selection is made, it can only be changed, not cleared. Use mandatory="force" to automatically select the first non-disabled option on mount:

Free

Basic features

Pro

Advanced features

Enterprise

Custom solutions

Selected plan:

<script setup lang="ts">
  import { Radio } from '@vuetify/v0'
  import { ref } from 'vue'

  const plan = ref<string>()

  const plans = [
    { value: 'free', label: 'Free', description: 'Basic features' },
    { value: 'pro', label: 'Pro', description: 'Advanced features' },
    { value: 'enterprise', label: 'Enterprise', description: 'Custom solutions' },
  ]
</script>

<template>
  <Radio.Group v-model="plan" class="flex flex-col gap-3" mandatory="force">
    <label
      v-for="item in plans"
      :key="item.value"
      class="flex items-start gap-3 p-3 border rounded-lg border-divider has-[:checked]:border-primary has-[:checked]:bg-primary/5 cursor-pointer"
    >
      <Radio.Root
        class="size-5 mt-0.5 border rounded-full inline-flex items-center justify-center border-divider data-[state=checked]:border-primary"
        :value="item.value"
      >
        <Radio.Indicator class="size-2.5 rounded-full bg-primary" />
      </Radio.Root>
      <div>
        <div class="font-medium">{{ item.label }}</div>
        <div class="text-sm text-on-surface-variant">{{ item.description }}</div>
      </div>
    </label>
  </Radio.Group>

  <p class="mt-4 text-sm text-on-surface-variant">
    Selected plan: {{ plan }}
  </p>
</template>

Accessibility

The Radio components handle all ARIA attributes automatically:

role="radiogroup" on the Group
role="radio" on each Root
aria-checked reflects checked state
aria-disabled when radio is disabled
aria-required for form validation (set on Group)
aria-label from the label prop
Roving tabindex - only the selected radio (or first if none) is tabbable
Space key selects the focused radio
Arrow keys navigate between radios

For custom implementations, use renderless mode and bind the attrs slot prop to your element:

vue

<template>
  <Radio.Root v-slot="{ attrs }" renderless>
    <div v-bind="attrs">
      <!-- Custom radio visual -->
    </div>
  </Radio.Root>
</template>

Arrow keys provide circular navigation within a radio group:

Key	Action
`Space`	Select focused radio
`ArrowUp` / `ArrowLeft`	Move to previous radio
`ArrowDown` / `ArrowRight`	Move to next radio

Navigation automatically skips disabled items and wraps around.

Form Integration

Set the name prop on Radio.Group to enable form submission for all radios in the group:

vue

<template>
  <Radio.Group v-model="selected" name="size">
    <Radio.Root value="small">
      <Radio.Indicator />
      Small
    </Radio.Root>

    <Radio.Root value="large">
      <Radio.Indicator />
      Large
    </Radio.Root>
  </Radio.Group>
</template>

Each Radio.Root automatically renders a hidden native radio input with the shared name and its own value.

For custom form integration, use Radio.HiddenInput explicitly:

vue

<template>
  <Radio.Group>
    <Radio.Root value="a">
      <Radio.Indicator />

      <Radio.HiddenInput name="custom" value="override" />
    </Radio.Root>
  </Radio.Group>
</template>

API Reference

The following API details are for all variations of the Radio component.

Props

id

ID

Unique identifier (auto-generated if not provided)

Default: useId()

label

string

Optional display label (passed through to slot)

value

V

Value associated with this radio for group selection and form submission

name

string

Form field name - triggers auto hidden input when provided

form

string

Associate with a form by ID (for radios outside the form element)

disabled

MaybeRef<boolean>

Disables this radio (prevents selection and keyboard focus)

Default: false

namespace

string

Namespace for context provision to children (Indicator, HiddenInput)

Default: "v0:radio:root"

groupNamespace

string

Namespace for connecting to parent Radio.Group

Default: "v0:radio:group"

ariaLabelledby

string

ID of element that labels this radio

ariaDescribedby

string

ID of element that describes this radio

ariaInvalid

boolean

Marks the radio as invalid for form validation

Slots

default

RadioRootSlotProps<V>

Default slot with radio state, actions, and ARIA attributes

Props

namespace

string

Namespace for dependency injection

Default: "v0:radio:group"

disabled

boolean

Disables the entire radio group

Default: false

mandatory

boolean | "force"

Auto-selects the first non-disabled item on mount. Radio groups are inherently mandatory (selection can only be changed, not cleared), so `mandatory="force"` is the only meaningful option.

Default: false

ariaLabelledby

string

ID of element that labels this group

ariaDescribedby

string

ID of element that describes this group

ariaRequired

boolean

Whether a selection is required before form submission

name

string

Form field name - enables native form submission for all radios in group

Activation mode controlling when selection occurs: - `automatic` (default): Selection follows focus (arrow keys select) - `manual`: Selection requires explicit Enter/Space key press Per WAI-ARIA APG, radio groups should have selection follow focus by default. Use `manual` for toolbar radio groups or when deliberate selection is preferred.

Default: "automatic"

Default: "v0:radio:root"

Slots

default

RadioIndicatorSlotProps

Default slot for custom indicator content