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:

npm install @headlessui/react

Radio Groups are built using the RadioGroup, RadioGroup.Label, and RadioGroup.Option components.

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

import { useState } from 'react'
import { RadioGroup } from '@headlessui/react'

function MyRadioGroup() {
  let [plan, setPlan] = useState('startup')

  return (
    <RadioGroup value={plan} onChange={setPlan}>
      <RadioGroup.Label>Plan</RadioGroup.Label>
      <RadioGroup.Option value="startup">
        {({ checked }) => (
          <span className={checked ? 'bg-blue-200' : ''}>Startup</span>
        )}
      </RadioGroup.Option>
      <RadioGroup.Option value="business">
        {({ checked }) => (
          <span className={checked ? 'bg-blue-200' : ''}>Business</span>
        )}
      </RadioGroup.Option>
      <RadioGroup.Option value="enterprise">
        {({ checked }) => (
          <span className={checked ? 'bg-blue-200' : ''}>Enterprise</span>
        )}
      </RadioGroup.Option>
    </RadioGroup>
  )
}

Headless UI keeps track of a lot of state about each component, like which radiogroup option is currently checked, whether a popover is open or closed, or which item in a menu is currently active via the keyboard.

But because the components are headless and completely unstyled out of the box, you can't see this information in your UI until you provide the styles you want for each state yourself.

Each component exposes information about its current state via render props that you can use to conditionally apply different styles or render different content.

For example, the RadioGroup.Option component exposes an active state, which tells you if the option is currently focused via the mouse or keyboard, and a checked state, which tells you if that option matches the current value of the RadioGroup.

import { useState, Fragment } from 'react'
import { RadioGroup } from '@headlessui/react'
import { CheckIcon } from '@heroicons/react/20/solid'

const plans = ['Statup', 'Business', 'Enterprise']

function MyRadioGroup() {
  const [plan, setPlan] = useState(plans[0])

  return (
    <RadioGroup value={plan} onChange={setPlan}>
      <RadioGroup.Label>Plan</RadioGroup.Label>
      {plans.map((plan) => (
        /* Use the `active` state to conditionally style the active option. */
        /* Use the `checked` state to conditionally style the checked option. */
        <RadioGroup.Option key={plan} value={plan} as={Fragment}>
          {({ active, checked }) => (
            <li
              className={`${
                active ? 'bg-blue-500 text-white' : 'bg-white text-black'
              }`}
            >
              {checked && <CheckIcon />}
              {plan}
            </li>
          )}
        </RadioGroup.Option>
      ))}
    </RadioGroup>
  )
}

For the complete render prop API for each component, see the component API documentation.

Each component also exposes information about its current state via a data-headlessui-state attribute that you can use to conditionally apply different styles.

When any of the states in the render prop API are true, they will be listed in this attribute as space-separated strings so you can target them with a CSS attribute selector in the form [attr~=value].

For example, here's what the RadioGroup component with some child RadioGroup.Option components renders when the radio group is open and the second option is both checked and active:

<!-- Rendered `RadioGroup` -->
<div role="radiogroup">
  <li data-headlessui-state="">Statup</li>
  <li data-headlessui-state="active checked">Business</li>
  <li data-headlessui-state="">Enterprise</li>
</div>

If you are using Tailwind CSS, you can use the @headlessui/tailwindcss plugin to target this attribute with modifiers like ui-open:* and ui-active:*:

import { useState, Fragment } from 'react'
import { RadioGroup } from '@headlessui/react'
import { CheckIcon } from '@heroicons/react/20/solid'

const plans = ['Statup', 'Business', 'Enterprise']

function MyRadioGroup() {
  const [plan, setPlan] = useState(plans[0])

  return (
    <RadioGroup value={plan} onChange={setPlan}>
      <RadioGroup.Label>Plan</RadioGroup.Label>
      {plans.map((plan) => (
        <RadioGroup.Option
          key={plan}
          value={plan}
          className="ui-active:bg-blue-500 ui-active:text-white ui-not-active:bg-white ui-not-active:text-black"
        >
          <CheckIcon className="hidden ui-checked:block" />
          {plan}
        </RadioGroup.Option>
      ))}
    </RadioGroup>
  )
}

Unlike native HTML form controls which only allow you to provide strings as values, Headless UI supports binding complex objects as well.

import { useState } from 'react'
import { RadioGroup } from '@headlessui/react'

const plans = [
  { id: 1, name: 'Startup' },
  { id: 2, name: 'Business' },
  { id: 3, name: 'Enterprise' },
]
function MyRadioGroup() {
  const [plan, setPlan] = useState(plans[0])

  return (
    <RadioGroup value={plan} onChange={setPlan}>
      <RadioGroup.Label>Plan:</RadioGroup.Label>
      {plans.map((plan) => (
        <RadioGroup.Option key={plan.id} value={plan}>
          {plan.name}
        </RadioGroup.Option>
      ))}
    </RadioGroup>
  )
}

When binding objects as values, it's important to make sure that you use the same instance of the object as both the value of the RadioGroup as well as the corresponding RadioGroup.Option, otherwise they will fail to be equal and cause the radiogroup to behave incorrectly.

To make it easier to work with different instances of the same object, you can use the by prop to compare the objects by a particular field instead of comparing object identity:

import { RadioGroup } from '@headlessui/react'

const plans = [
  { id: 1, name: 'Startup' },
  { id: 2, name: 'Business' },
  { id: 3, name: 'Enterprise' },
]

function PlanPicker({ checkedPlan, onChange }) {
  return (
    <RadioGroup value={checkedPlan} by="id" onChange={onChange}>
      <RadioGroup.Label>Plan</RadioGroup.Label>
      {plans.map((plan) => (
        <RadioGroup.Option key={plan.id} value={plan}>
          {plan.name}
        </RadioGroup.Option>
      ))}
    </RadioGroup>
  )
}

You can also pass your own comparison function to the by prop if you'd like complete control over how objects are compared:

import { RadioGroup } from '@headlessui/react'

const plans = [
  { id: 1, name: 'Startup' },
  { id: 2, name: 'Business' },
  { id: 3, name: 'Enterprise' },
]

function comparePlans(a, b) {
  return a.name.toLowerCase() === b.name.toLowerCase()
}
function PlanPicker({ checkedPlan, onChange }) {
  return (
    <RadioGroup value={checkedPlan} by={comparePlans} onChange={onChange}>
      <RadioGroup.Label>Plan</RadioGroup.Label>
      {plans.map((plan) => (
        <RadioGroup.Option key={plan.id} value={plan}>
          {plan.name}
        </RadioGroup.Option>
      ))}
    </RadioGroup>
  )
}

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

import { useState } from 'react'
import { RadioGroup } from '@headlessui/react'

const plans = ['startup', 'business', 'enterprise']

function Example() {
  const [plan, setPlan] = useState(plans[0])

  return (
    <form action="/billing" method="post">
      <RadioGroup value={plan} onChange={setPlan} name="plan">
        <RadioGroup.Label>Plan</RadioGroup.Label>
        {plans.map((plan) => (
          <RadioGroup.Option key={plan} value={plan}>
            {plan}
          </RadioGroup.Option>
        ))}
      </RadioGroup>
      <button>Submit</button>
    </form>
  )
}

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" />

If you provide a defaultValue prop to the RadioGroup instead of a value, Headless UI will track its state internally for you, allowing you to use it as an uncontrolled component.

import { RadioGroup } from '@headlessui/react'

const plans = [
  { id: 1, name: 'Startup' },
  { id: 2, name: 'Business' },
  { id: 3, name: 'Enterprise' },
]

function Example() {
  return (
    <form action="/companies" method="post">
      <RadioGroup name="plan" defaultValue={plans[0]}>
        <RadioGroup.Label>Plan</RadioGroup.Label>
        {plans.map((plan) => (
          <RadioGroup.Option key={plan.id} value={plan}>
            {plan.name}
          </RadioGroup.Option>
        ))}
      </RadioGroup>
      <button>Submit</button>
    </form>
  )
}

This can simplify your code when using the combobox with HTML forms or with form APIs that collect their state using FormData instead of tracking it using React state.

Any onChange prop you provide will still be called when the component's value changes in case you need to run any side effects, but you won't need to use it to track the component's state yourself.

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

By default, RatioGroup.Label renders a label element and RadioGroup.Description 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 RadioGroup.Option or the root RadioGroup itself.

import { useState } from 'react'
import { RadioGroup } from '@headlessui/react'

function MyRadioGroup() {
  const [selected, setSelected] = useState('startup')

  return (
    <RadioGroup value={selected} onChange={setSelected}>
      {/* This label is for the root `RadioGroup`.  */}
      <RadioGroup.Label className="sr-only">Plan</RadioGroup.Label>

      <div className="rounded-md bg-white">
        <RadioGroup.Option
          value="startup"
          className={({ checked }) => `
            ${checked ? 'border-indigo-200 bg-indigo-50' : 'border-gray-200'}
            relative flex border p-4
          `}
        >
          {({ checked }) => (
            <div className="flex flex-col">
              {/* This label is for the `RadioGroup.Option`.  */}
              <RadioGroup.Label
                as="span"
                className={`${
                  checked ? 'text-indigo-900' : 'text-gray-900'
                } block text-sm font-medium`}
              >
                Startup
              </RadioGroup.Label>
              {/* This description is for the `RadioGroup.Option`.  */}
              <RadioGroup.Description
                as="span"
                className={`${
                  checked ? 'text-indigo-700' : 'text-gray-500'
                } block text-sm`}
              >
                Up to 5 active job postings
              </RadioGroup.Description>
            </div>
          )}
        </RadioGroup.Option>
      </div>
    </RadioGroup>
  )
}

Clicking a RadioGroup.Option will select it.

All interactions apply when a RadioGroup component is focused.

Command	Description
`ArrowDown` or `ArrowUp` or `ArrowLeft` or `ArrowRight`	Cycles through a RadioGroup's options
`Space` when no option is selected yet	Selects the first option
`Enter` when in a form	Submits the form

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.
`value`	—	`T \| undefined` The current selected value in the `RadioGroup`.
`defaultValue`	—	`T` The default value when using as an uncontrolled component.
`by`	—	`keyof T \| ((a: T, z: T) => boolean)` Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.
`onChange`	—	`() => void` The function called to update the `RadioGroup` value.
`disabled`	`false`	`boolean` Whether or not the `RadioGroup` and all of its `RadioGroup.Option`'s are disabled.
`name`	—	`String` The name used when using this component inside a form.

The wrapper component for each selectable option.

Prop	Default	Description
`as`	`div`	`String \| Component` The element or component the `RadioGroup.Option` should render as.
`value`	—	`T \| undefined` The value of the current `RadioGroup.Option`. The type should match the type of the `value` in the `RadioGroup` component.
`disabled`	`false`	`boolean` Whether or not the `RadioGroup.Option` is disabled.

Render 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 RadioGroup.Option component via the aria-labelledby attribute.

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

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

Prop	Default	Description
`as`	`div`	`String \| Component` The element or component the `RadioGroup.Description` 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.