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 or yarn:

# npm npm install @headlessui/react # Yarn yarn add @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> ) }

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

To style the selected RadioGroup.Option you can read the checked render 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.

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"> {/* Use the `checked` render prop to conditionally style the checked item. */}
{({ checked }) => (
<span className={checked ? 'bg-blue-200' : ''}>Startup</span>
)}
</RadioGroup.Option> {/* ... */} </RadioGroup> ) }

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.

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"> {/* Use both `active` and `checked` to differentiate between the active and checked states. */} {({ active, checked }) => ( <> <span className={`
${checked ? 'bg-indigo-600 ' : ''}
${active ? 'ring-2 ring-indigo-500' : ''}
w-4 h-4 rounded-full`
}
/>
Startup </> )} </RadioGroup.Option> {/* ... */} </RadioGroup> ) }

In addition to the active and checked render props available to the children of a RadioGroup.Option, the classNames prop also accepts a function with those same render props.

This means you can conditionally apply class names directly to the RadioGroup.Option component, which by default renders a div element.

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> {/* Use the render props to apply styling to the Option's `div` element. */} <RadioGroup.Option value="startup"
classNames={({ checked, active }) => `
${checked ? 'bg-indigo-600 ' : ''}
${active ? 'ring-2 ring-indigo-500' : ''}
`}
>
Startup </RadioGroup.Option> {/* ... */} </RadioGroup> ) }

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' export default function Example() { 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="bg-white rounded-md"> <RadioGroup.Option value="startup" className={({ checked }) => ` ${checked ? 'bg-indigo-50 border-indigo-200' : 'border-gray-200'} relative border p-4 flex `} > {({ checked }) => ( <div className="flex flex-col"> {/* This Label is for the `RadioGroup.Option`. */}
<RadioGroup.Label
as="span"
className={classNames(
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={classNames(
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.

CommandDescription

and when a RadioGroup is focused

Cycles through a RadioGroup's options

All relevant ARIA attributes are automatically managed.

The main Radio Group component.

PropDefaultDescription
asdiv
String | Component

The element or component the RadioGroup should render as.

value
T | undefined

The current selected value in the RadioGroup.

onChange
() => void

The function called to update the RadioGroup value.

disabledfalse
boolean

Whether or not the RadioGroup and all of its RadioGroup.Option's are disabled.

The wrapper component for each selectable option.

PropDefaultDescription
asdiv
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.

disabledfalse
boolean

Whether or not the RadioGroup.Option is disabled.

Render PropDescription
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.

PropDefaultDescription
aslabel
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.

PropDefaultDescription
asdiv
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.