Listbox
updatedNo dropdown. No surprises. A list to pick one or more options from, with icons, titles and descriptions.
Open Props in the corner of the example to try variant, size and disabled. Options are 28, 32, 36, 40 and 48px tall from xs to xl, as tall as a menu item or an input of the same size, and their text, icons, padding and gaps grow with them on the control scale. A disabled option cannot be selected, and the arrow keys skip it; a disabled listbox dims every option and ignores the pointer and the keyboard.
Installation
Usage
<script setup lang="ts">
import {
Listbox,
ListboxContent,
ListboxDescription,
ListboxIcon,
ListboxItem,
ListboxTitle,
} from '@/components/ui/listbox'
const channel = ref('email')
</script>
<template>
<Listbox v-model="channel" aria-label="Notify me by">
<ListboxItem value="email">
<ListboxIcon><MailIcon /></ListboxIcon>
<ListboxContent>
<ListboxTitle>Email</ListboxTitle>
<ListboxDescription>A daily digest at 9:00.</ListboxDescription>
</ListboxContent>
</ListboxItem>
</Listbox>
</template>
ListboxItem: one option; a selected one gets a tint and a checkListboxIcon: an icon at the startListboxContent: holdsListboxTitleandListboxDescription, or just put text in the item
Start typing, and the list jumps to the matching option.
Width classes and aria-label go straight on Listbox. Or put it in a Field.
Examples
Icons, titles and descriptions
ListboxIcon holds an icon at the start of the option. It is hidden from screen readers and turns --primary with the option. Icons are 16px unless they set their own size. Below they are 20px, which suits two lines of text.
Custom indicator
Replace the check in the indicator-icon slot. Here selection-behavior="replace" also keeps one plan chosen at all times: by default, clicking the selected option clears it.
Multiple
With multiple, v-model is an array and each click adds or removes an option. Screen readers announce the listbox as multi-select.
2 of 6 chosen
Groups
ListboxGroup gathers options under a ListboxGroupLabel, which also names the group for screen readers. ListboxSeparator draws a line between groups and is hidden from screen readers.
On select
ListboxItem fires select when it is clicked or chosen with the keyboard, with the value in event.detail.value. Call event.preventDefault() to run an action without selecting the option, which turns the listbox into a list of commands.
Nothing opened yet
In a scroll area
Long list? Put a variant="ghost" listbox in a ScrollArea and move the border to the scroll area. Arrow keys keep the highlighted option in view.
Field
In a required field the listbox gets aria-required, and when the field is invalid, aria-invalid and a --destructive frame. Press Continue without choosing a region.
API Reference
Every part accepts class, merged over its base classes.
Listbox
| Prop | Default | Type and description |
|---|---|---|
| modelValue | — | AcceptableValue | AcceptableValue[]The selected value, or an array of them with |
| defaultValue | — | AcceptableValue | AcceptableValue[]The starting selection when |
| multiple | — | booleanLets more than one option be selected. |
| orientation | — | DataOrientation
|
| dir | — | DirectionReading direction for arrow keys. |
| disabled | — | booleanDisables every option. Also set by a disabled field. |
| selectionBehavior | — | "toggle" | "replace"
|
| highlightOnHover | — | booleanMoves the keyboard highlight with the pointer, as in a menu. |
| loop | — | booleanWraps arrow-key navigation from the last option to the first and back. Needs |
| by | — | string | ((a: AcceptableValue, b: AcceptableValue) => boolean)Compares object values by this key, or with this function, instead of by reference. |
| asChild | — | booleanRender the single child instead of the root, merging the root's attributes onto it. |
| as | — | AsTag | ComponentThe element or component to render for the root. |
| name | — | stringSubmits the selection with its form under this name. |
| required | — | booleanMarks the listbox required. Also set by a required field. |
| id | — | stringOverrides the |
| variant | — | "outline" | "ghost" | null
|
| size | "md" | ListboxSizeSets the height, padding, gap, icon and text of the options, from |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: AcceptableValue]Fires when the selection changes. |
| highlight | [payload: { ref: HTMLElement; value: AcceptableValue; } | undefined]Fires when the highlighted option changes, with |
| entryFocus | [event: CustomEvent<any>]Fires when focus enters the listbox. Call |
| leave | [event: Event]Fires when the pointer leaves the listbox. |
| Slot | Scope and description |
|---|---|
| default | {}The options, groups and separators. |
ListboxItem
| Prop | Default | Type and description |
|---|---|---|
| value* | — | AcceptableValueThe value this option puts in |
| disabled | — | booleanKeeps the option from being selected or highlighted. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the option's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| select | [event: SelectEvent$3<AcceptableValue>]Fires when the option is clicked or chosen with the keyboard, with the value in |
| Slot | Scope and description |
|---|---|
| default | {}The label, or a |
| indicator-icon | {}The icon shown at the end of a selected option, a check by default. |
ListboxGroupLabel
| Prop | Default | Type and description |
|---|---|---|
| for | — | stringSets the |
| asChild | — | booleanRender the single child instead of a wrapper, merging the label's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}The group's name, which also names the group for screen readers. |
ListboxContent
| Slot | Scope and description |
|---|---|
| default | {}A title and its description, stacked. |
ListboxDescription
| Slot | Scope and description |
|---|---|
| default | {}Supporting text under the title. |
ListboxGroup
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}A |
ListboxIcon
| Slot | Scope and description |
|---|---|
| default | {}An icon at the start of the option. Hidden from screen readers. |
ListboxSeparator
No props, events, slots or exposed members.
ListboxTitle
| Slot | Scope and description |
|---|---|
| default | {}The option's name, cut to one line. |
Props
- modelValue
AcceptableValue | AcceptableValue[]The selected value, or an array of them withmultiple, bound withv-model.- defaultValue
AcceptableValue | AcceptableValue[]The starting selection whenv-modelis not used.- multiple
booleanLets more than one option be selected.- orientation
DataOrientationhorizontallays the options out in a row and moves between them with left and right.- dir
DirectionReading direction for arrow keys.- disabled
booleanDisables every option. Also set by a disabled field.- selectionBehavior
"toggle" | "replace"toggleselects and clears an option on each click, so clicking the selected option clears it.replacekeeps a single-select listbox from ever emptying, and in a multiple one makes a click replace the selection unless Ctrl or Shift is held.- highlightOnHover
booleanMoves the keyboard highlight with the pointer, as in a menu.- loop
booleanWraps arrow-key navigation from the last option to the first and back. Needsreka-ui2.11 or later.- by
string | ((a: AcceptableValue, b: AcceptableValue) => boolean)Compares object values by this key, or with this function, instead of by reference.- asChild
booleanRender the single child instead of the root, merging the root's attributes onto it.- as
AsTag | ComponentThe element or component to render for the root.- name
stringSubmits the selection with its form under this name.- required
booleanMarks the listbox required. Also set by a required field.- id
stringOverrides theidtaken from a surrounding field.- variant
"outline" | "ghost" | nulloutlinedraws a card-like frame around the options;ghostdraws none, for a listbox inside another surface.- size
"md" ListboxSizeSets the height, padding, gap, icon and text of the options, fromxstoxl, after the [control scale](/docs/getting-started/sizing).mdis the default.
Emits
- update:modelValue
[value: AcceptableValue]Fires when the selection changes.- highlight
[payload: { ref: HTMLElement; value: AcceptableValue; } | undefined]Fires when the highlighted option changes, with{ ref, value }.- entryFocus
[event: CustomEvent<any>]Fires when focus enters the listbox. CallpreventDefault()to keep the first option from being highlighted.- leave
[event: Event]Fires when the pointer leaves the listbox.
Slots
- default
{}The options, groups and separators.
Props
- value*
AcceptableValueThe value this option puts inv-model.- disabled
booleanKeeps the option from being selected or highlighted.- asChild
booleanRender the single child instead of a wrapper, merging the option's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- select
[event: SelectEvent$3<AcceptableValue>]Fires when the option is clicked or chosen with the keyboard, with the value inevent.detail.value. Callevent.preventDefault()to run an action without selecting it.
Slots
- default
{}The label, or aListboxIconand aListboxContent.- indicator-icon
{}The icon shown at the end of a selected option, a check by default.
Props
- for
stringSets theforattribute, for when the label renders as a<label>withas.- asChild
booleanRender the single child instead of a wrapper, merging the label's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The group's name, which also names the group for screen readers.
Slots
- default
{}A title and its description, stacked.
Slots
- default
{}Supporting text under the title.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}AListboxGroupLabeland the options in the group.
Slots
- default
{}An icon at the start of the option. Hidden from screen readers.
Slots
- default
{}The option's name, cut to one line.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| listbox | data-variant, data-size, data-orientation, data-disabled | The element with role="listbox". Receives class and attributes. |
| listbox-root | — | Reka UI's root, laid out with display: contents. |
| listbox-item | data-state, data-highlighted, data-disabled | One option. data-state is checked or unchecked; data-highlighted marks the option the keyboard is on. |
| listbox-item-indicator | — | The check at the end of a selected option. |
| listbox-icon | — | The icon at the start of an option. |
| listbox-content | — | The column holding the title and description. |
| listbox-title | — | The option's name. |
| listbox-description | — | The supporting text. |
| listbox-group | — | A group of options. |
| listbox-group-label | — | The group's name. |
| listbox-separator | — | The line between groups. |