Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

RadioGroup

Native radios grouped by a fieldset and legend.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Plan

Install

Run in your project
bunx --bun @getweini/cli@latest add radio-group

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Plan
Vue
<script setup lang="ts">
import { ref } from 'vue'
import RadioGroup from './components/ui/radio-group/RadioGroup.vue'
import RadioGroupItem from './components/ui/radio-group/RadioGroupItem.vue'

const plan = ref<string | number>('personal')
</script>

<template>
  <RadioGroup v-model="plan" name="plan">
    <template #legend>Plan</template>
    <RadioGroupItem value="personal">Personal</RadioGroupItem>
    <RadioGroupItem value="team">Team</RadioGroupItem>
  </RadioGroup>
</template>

RadioGroupItem must be inside RadioGroup. Use the legend slot to name the group.

When to use it

Mutually exclusive plans

Choose one subscription plan and submit its scalar value.

Delivery preference

Show two short choices in a horizontal fieldset.

More examples

Subscription plan

The legend names the native radio fieldset.

Subscription plan
<script setup lang="ts">
import { ref } from 'vue'
import RadioGroup from './components/ui/radio-group/RadioGroup.vue'
import Radio from './components/ui/radio-group/RadioGroupItem.vue'

const plan = ref<string | number>('monthly')
</script>
<template>
  <RadioGroup v-model="plan" name="plan" required>
    <template #legend>Billing plan</template>
    <Radio value="monthly">Monthly</Radio>
    <Radio value="annual">Annual</Radio>
  </RadioGroup>
</template>

Delivery speed

Orientation changes layout while native radio behavior stays intact.

Delivery speed
<script setup lang="ts">
import { ref } from 'vue'
import RadioGroup from './components/ui/radio-group/RadioGroup.vue'
import Radio from './components/ui/radio-group/RadioGroupItem.vue'

const speed = ref<string | number>('standard')
</script>
<template>
  <RadioGroup v-model="speed" name="delivery" orientation="horizontal">
    <template #legend>Delivery speed</template>
    <Radio value="standard">Standard</Radio>
    <Radio value="express">Express</Radio>
  </RadioGroup>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Radio

Complete API for Radio
NameType or signatureDefaultWhat it does
valuepropstring | numberRequiredValue represented by this control or option.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
defaultslot() => unknownRequiredContent shown inside Radio.
elementexposedHTMLInputElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.

RadioGroup

Complete API for RadioGroup
NameType or signatureDefaultWhat it does
namepropstring | undefinedNot setName used when this control submits a value with a form.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
orientationprop"horizontal" | "vertical" | undefined"vertical"Arrange items horizontally or vertically.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
modelValuemodelstring | number | undefinedNot setCurrent value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: string | number | undefined]—Requests a new model value from the parent.
defaultslot() => unknownRequiredContent shown inside RadioGroup.
legendslot() => unknownRequiredContent for the legend area of RadioGroup.
errorslot((props: { message: string; messages: string[]; }) => unknown) | undefinedOptionalContent for the error area of RadioGroup.

RadioGroupItem

Complete API for RadioGroupItem
NameType or signatureDefaultWhat it does
valuepropstring | numberRequiredValue represented by this control or option.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
defaultslot() => unknownRequiredContent shown inside RadioGroupItem.
elementexposedHTMLInputElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
Public type definitions
Public types
// packages/frameworks/vue/components/radio-group/types.ts
// ------- TYPES -------

export interface RadioGroupProps {
  name?: string
  disabled?: boolean
  required?: boolean
  invalid?: boolean
  orientation?: 'horizontal' | 'vertical'
  form?: string
}

export interface RadioProps {
  value: string | number
  disabled?: boolean
  id?: string
}

Implementation notes

  • Radio must be rendered inside RadioGroup; the root owns the shared model.
  • Use different name values for unrelated groups in the same form.

Accessibility and localization

  • Provide a legend for each group. Native radios handle arrow keys, Space, and tab stops.

Source contract and editing guidance