GitHub repository

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:

npm install @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>
  )
}

Headless UI keeps track of a lot of state about each component, like which listbox option is currently selected, 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 Listbox.Option component exposes an active state, which tells you if the option is currently focused via the mouse or keyboard, and a selected state, which tells you if that option matches the current value of the Listbox.

import { useState, Fragment } from 'react'
import { Listbox } from '@headlessui/react'
import { CheckIcon } from '@heroicons/react/20/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>
  )
}

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 Listbox.Options component with some child Listbox.Option components renders when the listbox is open and the second option is both selected and active:

<!-- Rendered `Listbox.Options` -->
<ul data-headlessui-state="open">
  <li data-headlessui-state="">Wade Cooper</li>
  <li data-headlessui-state="active selected">Arlene Mccoy</li>
  <li data-headlessui-state="">Devon Webb</li>
</ul>

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 } from 'react'
import { Listbox } from '@headlessui/react'
import { CheckIcon } from '@heroicons/react/20/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) => (
          <Listbox.Option
            key={person.id}
            value={person}

            className="ui-active:bg-blue-500 ui-active:text-white ui-not-active:bg-white ui-not-active:text-black"
          >

            <CheckIcon className="hidden ui-selected:block" />
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

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 { 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>
  )
}

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 Listbox as well as the corresponding Listbox.Option, otherwise they will fail to be equal and cause the listbox 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 { Listbox } from '@headlessui/react'

const departments = [
  { id: 1, name: 'Marketing', contact: 'Durward Reynolds' },
  { id: 2, name: 'HR', contact: 'Kenton Towne' },
  { id: 3, name: 'Sales', contact: 'Therese Wunsch' },
  { id: 4, name: 'Finance', contact: 'Benedict Kessler' },
  { id: 5, name: 'Customer service', contact: 'Katelyn Rohan' },
]


function DepartmentPicker({ selectedDepartment, onChange }) {
  return (

    <Listbox value={selectedDepartment} by="id" onChange={onChange}>
      <Listbox.Button>{selectedDepartment.name}</Listbox.Button>
      <Listbox.Options>
        {departments.map((department) => (
          <Listbox.Option key={department.id} value={department}>
            {department.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

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

import { Listbox } from '@headlessui/react'

const departments = [
  { id: 1, name: 'Marketing', contact: 'Durward Reynolds' },
  { id: 2, name: 'HR', contact: 'Kenton Towne' },
  { id: 3, name: 'Sales', contact: 'Therese Wunsch' },
  { id: 4, name: 'Finance', contact: 'Benedict Kessler' },
  { id: 5, name: 'Customer service', contact: 'Katelyn Rohan' },
]


function compareDepartments(a, b) {
  return a.name.toLowerCase() === b.name.toLowerCase()
}

function DepartmentPicker({ selectedDepartment, onChange }) {
  return (
    <Listbox
      value={selectedDepartment}

      by={compareDepartments}
      onChange={onChange}
    >
      <Listbox.Button>{selectedDepartment.name}</Listbox.Button>
      <Listbox.Options>
        {departments.map((department) => (
          <Listbox.Option key={department.id} value={department}>
            {department.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

To allow selecting multiple values in your listbox, use the multiple prop and pass an array to value instead of a single option.

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 [selectedPeople, setSelectedPeople] = useState([people[0], people[1]])

  return (

    <Listbox value={selectedPeople} onChange={setSelectedPeople} multiple>
      <Listbox.Button>
        {selectedPeople.map((person) => person.name).join(', ')}
      </Listbox.Button>
      <Listbox.Options>
        {people.map((person) => (
          <Listbox.Option key={person.id} value={person}>
            {person.name}
          </Listbox.Option>
        ))}
      </Listbox.Options>
    </Listbox>
  )
}

This will keep the listbox open when you are selecting options, and choosing an option will toggle it in place.

Your onChange handler will be called with an array containing all selected options any time an option is added or removed.

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>
  )
}

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 { 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 Example() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (
    <form action="/projects/1/assignee" method="post">
      <Listbox
        value={selectedPerson}
        onChange={setSelectedPerson}

        name="assignee"
      >
        <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>
      <button>Submit</button>
    </form>
  )
}

This lets you use a listbox inside a native HTML <form> and make traditional form submissions as if your listbox 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="assignee[id]" value="1" />
<input type="hidden" name="assignee[name]" value="Durward Reynolds" />

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

You can access the currently selected option via the value render prop on the Listbox and Listbox.Button components.

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 Example() {
  return (
    <form action="/projects/1/assignee" method="post">

      <Listbox name="assignee" defaultValue={people[0]}>
        <Listbox.Button>{({ value }) => value.name}</Listbox.Button>
        <Listbox.Options>
          {people.map((person) => (
            <Listbox.Option key={person.id} value={person}>
              {person.name}
            </Listbox.Option>
          ))}
        </Listbox.Options>
      </Listbox>
      <button>Submit</button>
    </form>
  )
}

This can simplify your code when using the listbox 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.

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, the `Listbox.Options` 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 the `static` prop, the `Listbox.Options` are always
                rendered and the `open` state is ignored.
              */}

              <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>
  )
}

By default our built-in Transition component automatically communicates with the Listbox components to handle the open/closed states. However, if you require more control over this behavior, you can explicitly control it:

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. By contrast, Listbox does not render an element, and instead renders its children directly.

Use the as prop to render a component as a different element or as your own custom component, making sure your custom components forward refs so that Headless UI can wire things up correctly.

import { forwardRef, 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' },
]


let MyCustomButton = forwardRef(function (props, ref) {
  return <button className="..." ref={ref} {...props} />
})

function MyListbox() {
  const [selectedPerson, setSelectedPerson] = useState(people[0])

  return (

    <Listbox as="div" value={selectedPerson} onChange={setSelectedPerson}>
      <Listbox.Button as={MyCustomButton}>
        {selectedPerson.name}
      </Listbox.Button>


      <Listbox.Options as="div">
        {people.map((person) => (

          <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>
  )
}

If you've styled your Listbox.Options to appear horizontally, use the horizontal prop on the Listbox component to enable navigating the items with the left and right arrow keys instead of up and down, and to update the aria-orientation attribute for assistive technologies.

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} horizontal>
      <Listbox.Button>{selectedPerson.name}</Listbox.Button>
      <Listbox.Options className="flex flex-row">
        {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

ArrowDown or ArrowUp when listbox is open

Focuses previous/next non-disabled item

ArrowLeft or ArrowRight when listbox is open and horizontal is set

Focuses previous/next non-disabled item

Home or PageUp when listbox is open

Focuses first non-disabled item

End or PageDown when listbox is open

Focuses 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.

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—
(value: T) => void

The function to call when a new option is selected.

horizontalfalse
Boolean

When true, the orientation of the Listbox.Options will be horizontal, otherwise it will be vertical.

name—
String

The name used when using this component inside a form.

multiplefalse
Boolean

Whether multiple options can be selected or not.

Render PropDescription
value

T

The selected value.

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
value

T

The selected value.

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 directly 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.

Explore more predesigned examples→