Radio Group

Radio Groups give you the same functionality as native HTML radio inputs, without any of the styling. They're perfect for building out custom UIs for selectors.

To get started, install Headless UI via npm.

Please note that this library only supports Vue 3.

npm install @headlessui/vue

Radio Groups are built using the RadioGroup, RadioGroupLabel, and RadioGroupOption components.

Clicking an option will select it, and when the Radio Group is focused, the arrow keys will change the selected option.

<template>
  <RadioGroup v-model="plan">
    <RadioGroupLabel>Plan</RadioGroupLabel>
    <RadioGroupOption v-slot="{ checked }" value="startup">
      <span :class="checked ? 'bg-blue-200' : ''">Startup</span>
    </RadioGroupOption>
    <RadioGroupOption v-slot="{ checked }" value="business">
      <span :class="checked ? 'bg-blue-200' : ''">Business</span>
    </RadioGroupOption>
    <RadioGroupOption v-slot="{ checked }" value="enterprise">
      <span :class="checked ? 'bg-blue-200' : ''">Enterprise</span>
    </RadioGroupOption>
  </RadioGroup>
</template>

<script setup>
  import { ref } from 'vue'
  import {
    RadioGroup,
    RadioGroupLabel,
    RadioGroupOption,
  } from '@headlessui/vue'

  const plan = ref('startup')
</script>

This is a headless component so there are no styles included by default. Instead, the components expose useful information via scoped slots that you can use to apply the styles you'd like to apply yourself.

To style the selected RadioGroupOption you can read the checked slot prop argument, which tells you whether or not that option is the one that's currently selected.

You can use this state to conditionally apply whatever styles you like.

<template>
  <RadioGroup v-model="plan">
    <RadioGroupLabel>Plan</RadioGroupLabel>
    <RadioGroupOption value="startup" v-slot="{ checked }">
      <!--
        Use the `checked` slot prop to conditionally style the checked item.
      -->
      <span :class="checked ? 'bg-blue-200' : ''">Startup</span>
    </RadioGroupOption>

    <!-- ... -->
  </RadioGroup>
</template>

<script setup>
  import { ref } from 'vue'
  import {
    RadioGroup,
    RadioGroupLabel,
    RadioGroupOption,
  } from '@headlessui/vue'

  const plan = ref('startup')
</script>

Radio Group items can also be in an active state if they are focused with either the mouse or the keyboard.

It's a good idea to add styles specifically for this state, so users know when a group currently has focus.

<template>
  <RadioGroup v-model="plan">
    <RadioGroupLabel>Plan</RadioGroupLabel>
    <RadioGroupOption value="startup" v-slot="{ active, checked }">
      <!--
        Use both `active` and `checked` to differentiate between the
        active and checked states.
      -->
      <span
        :class='[
          checked ? "bg-indigo-600 " : "",
          active ? "ring-2 ring-indigo-500" : ""
        ]'
        class="h-4 w-4 rounded-full"
      />
      Startup
    </RadioGroupOption>

    <!-- ... -->
  </RadioGroup>
</template>

<script setup>
  import { ref } from 'vue'
  import {
    RadioGroup,
    RadioGroupLabel,
    RadioGroupOption,
  } from '@headlessui/vue'

  const plan = ref('startup')
</script>

If you add the name prop to your listbox, hidden input elements will be rendered and kept in sync with your selected value.

<template>
  <form action="/billing" method="post">
    <RadioGroup v-model="plan" name="plan">
      <RadioGroupLabel>Plan</RadioGroupLabel>
      <RadioGroupOption v-for="plan in plans" :key="plan" :value="plan">
        {{ plan }}
      </RadioGroupOption>
    </RadioGroup>
    <button>Submit</button>
  </form>
</template>

<script setup>
  import { ref } from 'vue'
  import {
    RadioGroup,
    RadioGroupLabel,
    RadioGroupOptions,
    RadioGroupOption,
  } from '@headlessui/vue'

  const plans = ['startup', 'business', 'enterprise']
  const plan = ref(plans[0])
</script>

This lets you use a radio group inside a native HTML <form> and make traditional form submissions as if your radio group was a native HTML form control.

Basic values like strings will be rendered as a single hidden input containing that value, but complex values like objects will be encoded into multiple inputs using a square bracket notation for the names.

<input type="hidden" name="plan" value="startup" />

You can use the RadioGroupLabel and RadioGroupDescription components to mark up each option's contents. Doing so will automatically link each component to its ancestor RadioGroupOption component via the aria-labelledby and aria-describedby attributes and autogenerated ids, improving the semantics and accessibility of your custom selector.

By default, RatioGroupLabel renders a label element and RadioGroupDescription renders a <div>. These can also be customized using the as prop, as described in the API docs below.

Note also that Labels and Descriptions can be nested. Each one will refer to its nearest ancestor component, whether than ancestor is a RadioGroupOption or the root RadioGroup itself.

<template>
  <RadioGroup v-model="plan">
    <!-- This Label is for the root `RadioGroup` -->
    <RadioGroupLabel class="sr-only">Plan</RadioGroupLabel>
    <div class="rounded-md bg-white">
      <RadioGroupOption value="startup" as="template" v-slot="{ checked }">
        <div
          :class='checked ? "bg-indigo-50 border-indigo-200" : "border-gray-200"'
          class="relative flex border p-4"
        >
          <div class="flex flex-col">
            <!-- This Label is for the `RadioGroupOption` -->
            <RadioGroupLabel as="template">
              <span
                :class='checked ? "text-indigo-900" : "text-gray-900"'
                class="block text-sm font-medium"
                >Startup</span
              >
            </RadioGroupLabel>
            <!-- This Description is for the `RadioGroupOption` -->
            <RadioGroupDescription as="template">
              <span
                :class='checked ? "text-indigo-700" : "text-gray-500"'
                class="block text-sm"
                >Up to 5 active job postings</span
              >
            </RadioGroupDescription>
          </div>
        </div>
      </RadioGroupOption>
    </div>
  </RadioGroup>
</template>

<script setup>
  import { ref } from 'vue'
  import {
    RadioGroup,
    RadioGroupLabel,
    RadioGroupOption,
  } from '@headlessui/vue'

  const plan = ref('startup')
</script>

Clicking a RadioGroupOption will select it.

Command	Description
`ArrowDown` or `ArrowUp` when a `RadioGroup` is focused	Cycles through a RadioGroup's options

All relevant ARIA attributes are automatically managed.

The main Radio Group component.

Prop	Default	Description
`as`	`div`	`String \| Component` The element or component the `RadioGroup` should render as.
`v-model`	—	`T` The selected value.
`disabled`	`false`	`boolean` Whether or not the `RadioGroup` and all of its `RadioGroupOption`'s' are disabled.

The wrapper component for each selectable option.

Prop	Default	Description
`as`	`div`	`String \| Component` The element or component the `RadioGroupOption` should render as.
`value`	—	`T \| undefined` The value of the current `RadioGroupOption`. The type should match the type of the `value` in the `RadioGroup` component.
`disabled`	`false`	`boolean` Whether or not the `RadioGroupOption` is disabled.
`name`	—	`String` The name used when using this component inside a form.

Slot Prop	Description
`active`	`Boolean` Whether or not the option is active (using the mouse or keyboard).
`checked`	`Boolean` Whether or not the current option is the checked value.
`disabled`	`boolean` Whether or not the current option is disabled.

Renders an element whose id attribute is automatically generated, and is then linked to its nearest ancestor RadioGroup or RadioGroupOption component via the aria-labelledby attribute.

Prop	Default	Description
`as`	`label`	`String \| Component` The element or component the `RadioGroupLabel` should render as.

Renders an element whose id attribute is automatically generated, and is then linked to its nearest ancestor RadioGroup or RadioGroupOption component via the aria-describedby attribute.

Prop	Default	Description
`as`	`div`	`String \| Component` The element or component the `RadioGroupDescription` should render as.

If you're interested in predesigned component examples using Headless UI and Tailwind CSS, check out Tailwind UI — a collection of beautifully designed and expertly crafted components built by us.

It's a great way to support our work on open-source projects like this and makes it possible for us to improve them and keep them well-maintained.