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.
Please note that this library only supports Vue 3.
npm install @headlessui/vue
Listboxes are built using the Listbox
, ListboxButton
, ListboxOptions
, ListboxOption
and ListboxLabel
components.
The ListboxButton
will automatically open/close the ListboxOptions
when clicked, and when the menu is open, the list of items receives focus and is automatically navigable via the keyboard.
<template> <Listbox v-model="selectedPerson"> <ListboxButton>{{ selectedPerson.name }}</ListboxButton> <ListboxOptions> <ListboxOption v-for="person in people" :key="person" :value="person" :disabled="person.unavailable" > {{ person.name }} </ListboxOption> </ListboxOptions> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' 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 }, ] const selectedPerson = ref(people[0]) </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 active ListboxOption
you can read the active
slot prop, 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 ListboxOption
you can read the selected
slot prop, 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.
<template> <Listbox v-model="selectedPerson"> <ListboxButton>{{ selectedPerson.name }}</ListboxButton> <ListboxOptions> <!-- Use the `active` state to conditionally style the active option. --> <!-- Use the `selected` state to conditionally style the selected option. --> <ListboxOption as="template"
v-slot="{ active, selected }"v-for="person in people" :key="person" :value="person" > <li :class="{'bg-blue-500 text-white': active,'bg-white text-black': !active}" ><CheckIcon v-show="selected" />{{ person.name }} </li> </ListboxOption> </ListboxOptions> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' import { CheckIcon } from '@heroicons/vue/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' }, ] const selectedPerson = ref(people[0]) </script>
To allow selecting multiple values in your listbox, use the multiple
prop and pass an array to v-model
instead of a single option.
<template>
<Listbox v-model="selectedPeople" multiple><ListboxButton> {{ selectedPeople.map((person) => person.name).join(', ') }} </ListboxButton> <ListboxOptions> <ListboxOption v-for="person in people" :key="person" :value="person"> {{ person.name }} </ListboxOption> </ListboxOptions> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' 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' }, ]const selectedPeople = ref([people[0], people[1]])</script>
This will keep the listbox open when you are selecting options, and choosing an option will toggle it in place.
Your v-model
binding will be updated 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 ListboxLabel
component.
<template> <Listbox v-model="selectedPerson">
<ListboxLabel>Assignee:</ListboxLabel><ListboxButton>{{ selectedPerson.name }}</ListboxButton> <ListboxOptions> <ListboxOption v-for="person in people" :key="person" :value="person"> {{ person.name }} </ListboxOption> </ListboxOptions> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxLabel, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' 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' }, ] const selectedPerson = ref(people[0]) </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="/projects/1/assignee" method="post">
<Listbox v-model="selectedPerson" name="assignee"><ListboxButton>{{ selectedPerson.name }}</ListboxButton> <ListboxOptions> <ListboxOption v-for="person in people" :key="person" :value="person"> {{ person.name }} </ListboxOption> </ListboxOptions> </Listbox> <button>Submit</button> </form> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' 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' }, ] const selectedPerson = ref(people[0]) </script>
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" />
By default, your ListboxOptions
instance will be shown/hidden automatically based on the internal open
state tracked within the Listbox
component itself.
<template> <Listbox v-model="selectedPerson"> <ListboxButton>{{ selectedPerson.name }}</ListboxButton> <!-- By default, this will automatically show/hide when the ListboxButton is pressed. --> <ListboxOptions> <ListboxOption v-for="person in people" :key="person" :value="person"> {{ person.name }} </ListboxOption> </ListboxOptions> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' const people = [ { name: 'Durward Reynolds' }, { name: 'Kenton Towne' }, { name: 'Therese Wunsch' }, { name: 'Benedict Kessler' }, { name: 'Katelyn Rohan' }, ] const selectedPerson = ref(people[0]) </script>
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 ListboxOptions
instance to tell it to always render, and inspect the open
slot prop provided by the Listbox
to control which element is shown/hidden yourself.
<template>
<Listbox v-model="selectedPerson" v-slot="{ open }"><ListboxButton>{{ selectedPerson.name }}</ListboxButton><div v-show="open"><!-- Using `static`, `ListboxOptions` is always rendered and ignores the `open` state. --><ListboxOptions static><ListboxOption v-for="person in people" :key="person" :value="person"> {{ person.name }} </ListboxOption> </ListboxOptions> </div> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' const people = [ { name: 'Durward Reynolds' }, { name: 'Kenton Towne' }, { name: 'Therese Wunsch' }, { name: 'Benedict Kessler' }, { name: 'Katelyn Rohan' }, ] const selectedPerson = ref(people[0]) </script>
Use the disabled
prop to disable a ListboxOption
. This will make it unselectable via mouse and keyboard, and it will be skipped when pressing the up/down arrows.
<template> <Listbox v-model="selectedPerson"> <ListboxButton>{{ selectedPerson.name }}</ListboxButton> <ListboxOptions> <!-- Disabled options will be skipped by keyboard navigation. --> <ListboxOption v-for="person in people" :key="person" :value="person"
:disabled="person.unavailable"> <span :class='{ "opacity-75": person.unavailable }'> {{ person.name }} </span> </ListboxOption> </ListboxOptions> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' const people = [ { name: 'Durward Reynolds', unavailable: true }, { name: 'Kenton Towne', unavailable: false }, { name: 'Therese Wunsch', unavailable: false }, { name: 'Benedict Kessler', unavailable: true }, { name: 'Katelyn Rohan', unavailable: false }, ] const selectedPerson = ref(people[0]) </script>
To animate the opening/closing of your listbox, you can use Vue's built-in <transition>
component. All you need to do is wrap your ListboxOptions
instance in a <transition>
, and the transition will be applied automatically.
<template> <Listbox v-model="selectedPerson"> <ListboxButton>{{ selectedPerson.name }}</ListboxButton> <!-- Use Vue's built-in <transition> component to add transitions. -->
<transitionenter-active-class="transition duration-100 ease-out"enter-from-class="transform scale-95 opacity-0"enter-to-class="transform scale-100 opacity-100"leave-active-class="transition duration-75 ease-out"leave-from-class="transform scale-100 opacity-100"leave-to-class="transform scale-95 opacity-0"><ListboxOptions> <ListboxOption v-for="person in people" :key="person" :value="person"> {{ person.name }} </ListboxOption> </ListboxOptions> </transition> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' 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' }, ] const selectedPerson = ref(people[0]) </script>
If you'd like to coordinate multiple transitions for different children of your Listbox, check out the Transition component included in Headless UI.
By default, the Listbox
and its subcomponents each render a default element that is sensible for that component.
For example, ListboxLabel
renders a label
by default, ListboxButton
renders a button
, ListboxOptions
renders a ul
, and ListboxOption
renders a li
. By contrast, Listbox
does not render an element, and
instead renders its children directly.
This is easy to change using the as
prop, which exists on every component.
<template> <!-- Render a `div` instead of nothing -->
<Listbox as="div" v-model="selectedPerson"><ListboxButton>{{ selectedPerson.name }}</ListboxButton> <!-- Render a `div` instead of a `ul` --><ListboxOptions as="div"><!-- Render a `span` instead of a `li` --> <ListboxOptionas="span"v-for="person in people" :key="person" :value="person" > {{ person.name }} </ListboxOption> </ListboxOptions> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' 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' }, ] const selectedPerson = ref(people[0]) </script>
To tell an element to render its children directly with no wrapper element, use as="template"
.
<template> <Listbox v-model="selectedPerson"> <!-- Render children directly instead of a `button` -->
<ListboxButton as="template"><button>{{ selectedPerson.name }}</button> </ListboxButton> <ListboxOptions> <ListboxOption v-for="person in people" :key="person" :value="person"> {{ person.name }} </ListboxOption> </ListboxOptions> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' 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' }, ] const selectedPerson = ref(people[0]) </script>
If you've styled your ListboxOptions
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.
<template>
<Listbox v-model="selectedPerson" horizontal><ListboxButton>{{ selectedPerson.name }}</ListboxButton> <ListboxOptions class="flex flex-row"> <ListboxOption v-for="person in people" :key="person" :value="person"> {{ person.name }} </ListboxOption> </ListboxOptions> </Listbox> </template> <script setup> import { ref } from 'vue' import { Listbox, ListboxButton, ListboxOptions, ListboxOption, } from '@headlessui/vue' 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' }, ] const selectedPerson = ref(people[0]) </script>
When a Listbox is toggled open, the ListboxOptions
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 ListboxButton
.
Clicking a ListboxButton
toggles the options list open and closed. Clicking anywhere outside of the options list will close the listbox.
Command | Description |
Enter, Space, ArrowDown, or ArrowUp when | 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 |
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 |
Prop | Default | Description |
as | template | String | Component The element or component the |
v-model | — | T The selected value. |
disabled | false | Boolean Use this to disable the entire Listbox component & related children. |
horizontal | false | Boolean When true, the orientation of the |
name | — | String The name used when using this component inside a form. |
multiple | false | Boolean Whether multiple options can be selected or not. |
Slot Prop | Description |
open |
Whether or not the Listbox is open. |
disabled |
Whether or not the Listbox is disabled. |
Prop | Default | Description |
as | button | String | Component The element or component the |
Slot Prop | Description |
open |
Whether or not the Listbox is open. |
disabled |
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.
Prop | Default | Description |
as | label | String | Component The element or component the |
Slot Prop | Description |
open |
Whether or not the Listbox is open. |
disabled |
Whether or not the Listbox is disabled. |
Prop | Default | Description |
as | ul | String | Component The element or component the |
static | false | Boolean Whether the element should ignore the internally managed open/closed state. |
unmount | true | Boolean Whether the element should be unmounted or hidden based on the open/closed state. |
Slot Prop | Description |
open |
Whether or not the Listbox is open. |
Prop | Default | Description |
value | — | T The option value. |
as | li | String | Component The element or component the |
disabled | false | Boolean Whether or not the option should be disabled for keyboard navigation and ARIA purposes. |
Slot Prop | Description |
active |
Whether or not the option is the active/focused option. |
selected |
Whether or not the option is the selected option. |
disabled |
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.