Listbox (Select)

Listboxes are a great foundation for building custom, accessible select menus for your app, complete with robust support for keyboard navigation.

To get started, install Headless UI via npm or yarn:

# npm npm install @headlessui/react # Yarn yarn add @headlessui/react

Listboxes are built using the Listbox, Listbox.Button, Listbox.Options, Listbox.Option and Listbox.Label components.

The Listbox.Button will automatically open/close the Listbox.Options when clicked, and when the menu is open, the list of items receives focus and is automatically navigable via the keyboard.

import { useState } from 'react' import { Listbox } from '@headlessui/react' const people = [ { id: 1, name: 'Durward Reynolds', unavailable: false }, { id: 2, name: 'Kenton Towne', unavailable: false }, { id: 3, name: 'Therese Wunsch', unavailable: false }, { id: 4, name: 'Benedict Kessler', unavailable: true }, { id: 5, name: 'Katelyn Rohan', unavailable: false }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( <Listbox value={selectedPerson} onChange={setSelectedPerson}> <Listbox.Button>{selectedPerson.name}</Listbox.Button> <Listbox.Options> {people.map((person) => ( <Listbox.Option key={person.id} value={person} disabled={person.unavailable} > {person.name} </Listbox.Option> ))} </Listbox.Options> </Listbox> ) }

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 active Listbox.Option you can read the active render prop argument, which tells you whether or not that listbox option is the option that is currently focused via the mouse or keyboard.

To style the selected Listbox.Option you can read the selected render prop argument, which tells you whether or not that listbox option is the option that is currently the value passed to the Listbox.

Note that an option can be both active and selected at the same time.

You can use this state to conditionally apply whatever active/focus styles you like, for instance a blue background like is typically used for native <select> elements. For the selected state, a checkmark is also common.

import { useState, Fragment } from 'react' import { Listbox } from '@headlessui/react' import { CheckIcon } from '@heroicons/react/solid' const people = [ { id: 1, name: 'Durward Reynolds' }, { id: 2, name: 'Kenton Towne' }, { id: 3, name: 'Therese Wunsch' }, { id: 4, name: 'Benedict Kessler' }, { id: 5, name: 'Katelyn Rohan' }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( <Listbox value={selectedPerson} onChange={setSelectedPerson}> <Listbox.Button>{selectedPerson.name}</Listbox.Button> <Listbox.Options> {people.map((person) => ( /* Use the `active` state to conditionally style the active option. */ /* Use the `selected` state to conditionally style the selected option. */ <Listbox.Option key={person.id} value={person} as={Fragment}>
{({ active, selected }) => (
<li className={`${
active ? 'bg-blue-500 text-white' : 'bg-white text-black'
}
`
}
>
{selected && <CheckIcon />}
{person.name} </li> )} </Listbox.Option> ))} </Listbox.Options> </Listbox> ) }

By default the Listbox will use the button contents as the label for screenreaders. If you'd like more control over what is announced to assistive technologies, use the Listbox.Label component.

import { useState } from 'react' import { Listbox } from '@headlessui/react' const people = [ { id: 1, name: 'Durward Reynolds' }, { id: 2, name: 'Kenton Towne' }, { id: 3, name: 'Therese Wunsch' }, { id: 4, name: 'Benedict Kessler' }, { id: 5, name: 'Katelyn Rohan' }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( <Listbox value={selectedPerson} onChange={setSelectedPerson}>
<Listbox.Label>Assignee:</Listbox.Label>
<Listbox.Button>{selectedPerson.name}</Listbox.Button> <Listbox.Options> {people.map((person) => ( <Listbox.Option key={person.id} value={person}> {person.name} </Listbox.Option> ))} </Listbox.Options> </Listbox> ) }

By default, your Listbox.Options instance will be shown/hidden automatically based on the internal open state tracked within the Listbox component itself.

import { useState } from 'react' import { Listbox } from '@headlessui/react' const people = [ { id: 1, name: 'Durward Reynolds' }, { id: 2, name: 'Kenton Towne' }, { id: 3, name: 'Therese Wunsch' }, { id: 4, name: 'Benedict Kessler' }, { id: 5, name: 'Katelyn Rohan' }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( <Listbox value={selectedPerson} onChange={setSelectedPerson}> <Listbox.Button>{selectedPerson.name}</Listbox.Button> {/* By default, this will automatically show/hide when the Listbox.Button is pressed. */} <Listbox.Options> {people.map((person) => ( <Listbox.Option key={person.id} value={person}> {person.name} </Listbox.Option> ))} </Listbox.Options> </Listbox> ) }

If you'd rather handle this yourself (perhaps because you need to add an extra wrapper element for one reason or another), you can add a static prop to the Listbox.Options instance to tell it to always render, and inspect the open render prop provided by Listbox to control which element is shown/hidden yourself.

import { useState } from 'react' import { Listbox } from '@headlessui/react' const people = [ { id: 1, name: 'Durward Reynolds' }, { id: 2, name: 'Kenton Towne' }, { id: 3, name: 'Therese Wunsch' }, { id: 4, name: 'Benedict Kessler' }, { id: 5, name: 'Katelyn Rohan' }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( <Listbox value={selectedPerson} onChange={setSelectedPerson}> {({ open }) => ( <> <Listbox.Button>{selectedPerson.name}</Listbox.Button>
{open && (
<div> {/* Using `static`, `Listbox.Options` is always rendered and ignores the `open` state. */}
<Listbox.Options static>
{people.map((person) => ( <Listbox.Option key={person.id} value={person}> {person.name} </Listbox.Option> ))} </Listbox.Options> </div> )} </> )} </Listbox> ) }

Use the disabled prop to disable a Listbox.Option. This will make it unselectable via mouse and keyboard, and it will be skipped when pressing the up/down arrows.

import { useState } from 'react' import { Listbox } from '@headlessui/react' const people = [ { id: 1, name: 'Durward Reynolds', unavailable: false }, { id: 2, name: 'Kenton Towne', unavailable: false }, { id: 3, name: 'Therese Wunsch', unavailable: false }, { id: 4, name: 'Benedict Kessler', unavailable: true }, { id: 5, name: 'Katelyn Rohan', unavailable: false }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( <Listbox value={selectedPerson} onChange={setSelectedPerson}> <Listbox.Button>{selectedPerson.name}</Listbox.Button> <Listbox.Options> {people.map((person) => ( /* Disabled options will be skipped by keyboard navigation. */ <Listbox.Option key={person.id} value={person}
disabled={person.unavailable}
>
<span className={person.unavailable ? 'opacity-75' : ''}> {person.name} </span> </Listbox.Option> ))} </Listbox.Options> </Listbox> ) }

To animate the opening/closing of the listbox panel, use the provided Transition component. All you need to do is wrap the Listbox.Options in a <Transition>, and the transition will be applied automatically.

import { useState } from 'react' import { Listbox, Transition } from '@headlessui/react' const people = [ { id: 1, name: 'Durward Reynolds' }, { id: 2, name: 'Kenton Towne' }, { id: 3, name: 'Therese Wunsch' }, { id: 4, name: 'Benedict Kessler' }, { id: 5, name: 'Katelyn Rohan' }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( <Listbox value={selectedPerson} onChange={setSelectedPerson}> <Listbox.Button>{selectedPerson.name}</Listbox.Button>
<Transition
enter="transition duration-100 ease-out"
enterFrom="transform scale-95 opacity-0"
enterTo="transform scale-100 opacity-100"
leave="transition duration-75 ease-out"
leaveFrom="transform scale-100 opacity-100"
leaveTo="transform scale-95 opacity-0"
>
<Listbox.Options> {people.map((person) => ( <Listbox.Option key={person.id} value={person}> {person.name} </Listbox.Option> ))} </Listbox.Options>
</Transition>
</Listbox> ) }

Our built-in components communicate with eachother, if you require more control over the behaviour, then you can use a more explicit version:

import { useState } from 'react' import { Listbox, Transition } from '@headlessui/react' const people = [ { id: 1, name: 'Durward Reynolds' }, { id: 2, name: 'Kenton Towne' }, { id: 3, name: 'Therese Wunsch' }, { id: 4, name: 'Benedict Kessler' }, { id: 5, name: 'Katelyn Rohan' }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( <Listbox value={selectedPerson} onChange={setSelectedPerson}>
{({ open }) => (
<>
<Listbox.Button>{selectedPerson.name}</Listbox.Button> {/* Use the Transition + open render prop argument to add transitions. */} <Transition
show={open}
enter="transition duration-100 ease-out" enterFrom="transform scale-95 opacity-0" enterTo="transform scale-100 opacity-100" leave="transition duration-75 ease-out" leaveFrom="transform scale-100 opacity-100" leaveTo="transform scale-95 opacity-0" >
{/* Don't forget to add `static` to your Listbox.Options! */}
<Listbox.Options static>
{people.map((person) => ( <Listbox.Option key={person.id} value={person}> {person.name} </Listbox.Option> ))} </Listbox.Options> </Transition>
</>
)}
</Listbox> ) }

Because they're renderless, Headless UI components also compose well with other animation libraries in the React ecosystem like Framer Motion and React Spring.

By default, the Listbox and its subcomponents each render a default element that is sensible for that component.

For example, Listbox.Label renders a label by default, Listbox.Button renders a button, Listbox.Options renders a ul, and Listbox.Option renders a li. Listbox interestingly does not render an extra element, and instead renders its children directly.

This is easy to change using the as prop, which exists on every component.

import { useState } from 'react' import { Listbox } from '@headlessui/react' const people = [ { id: 1, name: 'Durward Reynolds' }, { id: 2, name: 'Kenton Towne' }, { id: 3, name: 'Therese Wunsch' }, { id: 4, name: 'Benedict Kessler' }, { id: 5, name: 'Katelyn Rohan' }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( /* Render a `div` instead of a React.Fragment */
<Listbox as="div" value={selectedPerson} onChange={setSelectedPerson}>
<Listbox.Button>{selectedPerson.name}</Listbox.Button> {/* Render a `div` instead of a `ul` */}
<Listbox.Options as="div">
{people.map((person) => ( /* Render a `span` instead of a `li` */ <Listbox.Option as="span" key={person.id} value={person}>
{person.name}
</Listbox.Option> ))} </Listbox.Options> </Listbox> ) }

To tell an element to render its children directly with no wrapper element, use a Fragment.

import { useState, Fragment } from 'react' import { Listbox } from '@headlessui/react' const people = [ { id: 1, name: 'Durward Reynolds' }, { id: 2, name: 'Kenton Towne' }, { id: 3, name: 'Therese Wunsch' }, { id: 4, name: 'Benedict Kessler' }, { id: 5, name: 'Katelyn Rohan' }, ] function MyListbox() { const [selectedPerson, setSelectedPerson] = useState(people[0]) return ( <Listbox value={selectedPerson} onChange={setSelectedPerson}> {/* Render a `Fragment` instead of a `button` */}
<Listbox.Button as={Fragment}>
<button>{selectedPerson.name}</button> </Listbox.Button> <Listbox.Options> {people.map((person) => ( <Listbox.Option key={person.id} value={person}> {person.name} </Listbox.Option> ))} </Listbox.Options> </Listbox> ) }

When a Listbox is toggled open, the Listbox.Options receives focus. Focus is trapped within the list of items until Escape is pressed or the user clicks outside the options. Closing the Listbox returns focus to the Listbox.Button.

Clicking a Listbox.Button toggles the options list open and closed. Clicking anywhere outside of the options list will close the listbox.

CommandDescription

Enter, Space, ArrowDown, or ArrowUp when Listbox.Button is focused

Opens listbox and focuses the selected item

Esc when listbox is open

Closes listbox

ArrowDownor ArrowUp when listbox is open

Focuses previous/next non-disabled item

Home or End when listbox is open

Focuses first/last non-disabled item

Enter or Space when listbox is open

Selects the current item

A–Z or a–z when listbox is open

Focuses first item that matches keyboard input

All relevant ARIA attributes are automatically managed.

The main Listbox component.

PropDefaultDescription
asFragment
String | Component

The element or component the Listbox should render as.

disabledfalse
Boolean

Use this to disable the entire Listbox component & related children.

value
T

The selected value.

onChange
(value: T) => void

The function to call when a new option is selected.

Render PropDescription
open

Boolean

Whether or not the Listbox is open.

disabled

Boolean

Whether or not the Listbox is disabled.

The Listbox's button.

PropDefaultDescription
asbutton
String | Component

The element or component the Listbox.Button should render as.

Render PropDescription
open

Boolean

Whether or not the Listbox is open.

disabled

Boolean

Whether or not the Listbox is disabled.

A Label that can be used for more control over the text your Listbox will announce to screenreaders. Its id attribute will be automatically generated and linked to the root Listbox component via the aria-labelledby attribute.

PropDefaultDescription
aslabel
String | Component

The element or component the Listbox.Label should render as.

Render PropDescription
open

Boolean

Whether or not the Listbox is open.

disabled

Boolean

Whether or not the Listbox is disabled.

The component that direclty wraps the list of options in your custom Listbox.

PropDefaultDescription
asul
String | Component

The element or component the Listbox.Options should render as.

staticfalse
Boolean

Whether the element should ignore the internally managed open/closed state.

Note: static and unmount can not be used at the same time. You will get a TypeScript error if you try to do it.

unmounttrue
Boolean

Whether the element should be unmounted or hidden based on the open/closed state.

Note: static and unmount can not be used at the same time. You will get a TypeScript error if you try to do it.

Render PropDescription
open

Boolean

Whether or not the Listbox is open.

Used to wrap each item within your Listbox.

PropDefaultDescription
value
T

The option value.

asli
String | Component

The element or component the Listbox.Option should render as.

disabledfalse
Boolean

Whether or not the option should be disabled for keyboard navigation and ARIA purposes.

Render PropDescription
active

Boolean

Whether or not the option is the active/focused option.

selected

Boolean

Whether or not the option is the selected option.

disabled

Boolean

Whether or not the option is the disabled for keyboard navigation and ARIA purposes.

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.