Skip to content

Listbox

Select one or more values from a list.

Demos

Size
Vue
Tailwind CSS
Akaza UI

Usage

vue
<script setup lang="ts">
import { Accordion } from '~/components/ui/accordion'

const items = [
  { value: 'source', label: 'Do I own the source?', content: 'Yes. Copy and adapt the files.' },
]
</script>

<template>
  <Accordion :items="items" />
</template>

Installation

Complete the shared installation. Copy Listbox.vue and index.ts into app/components/ui/listbox/.

API

Variants and defaults

PropValuesDefault
sizexs, sm, md, lg, xlsm

Models

ModelTypeDefaultDescription
v-modelListboxValue | ListboxValue[]""Selected value or values.
v-model:searchstring""Filter input value.

Props

PropTypeDefaultDescription
optionsListboxOption[]requiredRows rendered by the listbox.
valueKeystring-Object key used as value.
labelKeystring"label"Object key used as label.
descriptionKeystring"description"Object key used as description.
disabledKeystring"disabled"Object key used as disabled state.
multiplebooleanfalseEnables multiple selection.
nullableValuestring""Empty value used by single selection and clear().
bystring | (a, b) => booleanObject.isValue comparator, including object identity by key.
serializeValue(value) => stringJSON/string conversionSerializes native form values and keys.
idstringfield/generated idHidden control id.
namestringfield nameNative form field name.
requiredbooleanfalseRequires at least one selected option.
disabledbooleanfalseDisables focus and selection.
readOnlybooleanfalseAllows navigation without value changes.
invalidbooleanfalseForces invalid styling and ARIA state.
autoFocusbooleanfalseFocuses the filter when present, otherwise the listbox, after mount.
loopbooleantrueWraps keyboard navigation.
orientation"vertical" | "horizontal""vertical"ARIA orientation and arrow-key axis.
dir"ltr" | "rtl""ltr"Horizontal keyboard direction.
selectionBehavior"toggle" | "replace""toggle"Multiple-selection behavior without modifier keys.
filterablebooleanfalseRenders the filter input.
filter(option, search) => booleanlabel contains searchCustom option filter.
filterPlaceholderstring"Filter options"Filter input placeholder.
emptyLabelstring"No options found."Default empty content.
highlightOnHoverbooleantruePointer hover changes the active option.
virtualizebooleanfalseEnables virtual rendering.
virtualItemHeightnumber40Virtual row height in px.
virtualHeightnumber240Virtual viewport height in px.
overscannumber5Extra virtual rows rendered outside the viewport.
ariaLabelstring-Accessible label when no visible label exists.
ariaLabelledbystring-Accessible label element id.
ariaDescribedbystringfield IDsAccessible description/error ids.
uiListboxUi-Classes for structural parts.

Slots

SlotPropsDescription
option or option slotoption, value, label, description, isSelected, isHighlighted, isDisabled, selectSelectable row content.
group-labeloption, labelGroup label content.
empty-Empty filtered state.

Events

EventPayloadDescription
value-change(value, details)Fires before selection changes. Cancelable.
search-change(search, details)Fires before filter text changes. Cancelable.
highlight-change(option, details)Fires before the active option changes. Cancelable.
entry-focus(option, details)Fires when focus enters the listbox and before initial highlight. Cancelable.
leave(option, details)Fires when the pointer leaves the listbox. Cancelable.

Keyboard

KeyBehavior
ArrowDown / ArrowUpMove through a vertical list.
ArrowRight / ArrowLeftMove through a horizontal list, respecting dir.
Home / EndMove to first/last enabled option.
Enter / SpaceSelect or toggle the active option.
Shift + ArrowExtend a multiple-selection range.
Ctrl+A / Cmd+ASelect all enabled visible options in multiple mode.
printable charactersTypeahead to a matching label.
filter EscapeClear non-empty filter text.