KListbox Candidate link to current page

release-v5 | Release notes

Overview
#

KListbox is a representation of the APG listbox pattern with several additional enhancements. It can be used as a standalone listbox or within a composite widget such as a dropdown or combobox.

Its options are provided via KListboxOption.

It supports both multi selection and single selection.

KListbox supports dynamic option sets (useful for integration with filtering, pagination, etc.). Currently rendered options are referred to as visible options. Selection state of hidden options is preserved.

Messages
#

KListbox requires a messages object. Each entry must be a translated string that is short and focused.

KListbox messages
Name Required Description Examples
clickable
Yes
Accessible description of the listbox to indicate that its options are clickable.
Options are clickable
allOptionsSelected
Yes
Announced via live region when all options are selected with Ctrl + A or when the select all checkbox is used.
All options selected
allOptionsDeselected
Yes
Announced via live region when all options are deselected with Ctrl + A or when the select all checkbox is used.
No options selected
optionDeselected
Yes
Announced via live region when an option is deselected.
Deselected
partiallySelected
No
Renders a visually-hidden text inside indeterminate options so screen readers announce the partial selection state. Use with grouped listboxes that have parent checkboxes.
Partially selected

Usage
#

Default
#

KListboxOption is a direct child of KListbox.

Select all
#

Use the #selectAll scoped slot together with a select control, typically KCheckbox, to implement the select all functionality. The slot provides:

  • allSelected: true when every visible option is selected.
  • someSelected: true when at least one (but not all) visible options are selected. Useful for indicating indeterminate state.
  • setAllSelected(checked): Controls selection of all visible options. Call with true to select all visible options or false to deselect them.

Single select
#

Set multiple="false" on the listbox. Options automatically hide the checkbox selector in single-select mode. Use the showSelector prop on KListboxOption to override this behaviour explicitly.

Customized
#

Apply style on the listbox and its rows to add more space, borders, or other appearance customizations. Use slots to show rich content.

Scrollable
#

To limit the space a long list takes up, apply a maximum height, and the list will become scrollable.

Grouped
#

Group options using KListboxGroup.

Related
#

Props
#

Name Description Type Default Required
id
#
Unique listbox ID
 string — true
value
#
Array of selected option values. Always an Array in both single and multi-select modes for a consistent v-model API.
 array — true
ariaLabel
#
Accessible label for the listbox. Provide either this or ariaLabelledBy.
 string null —
ariaLabelledBy
#
ID of an element that labels the listbox. Provide either this or ariaLabel.
 string null —
messages
#
Localized strings for screen reader announcements. Can be static strings or functions returning strings.
 object — true
multiple
#
Whether the listbox allows multiple selections. Controls both the aria-multiselectable ARIA attribute and the actual selection behavior: when false, re-clicking an already selected option does nothing, and selecting a new option replaces the current selection instead of adding to it.
 boolean true —

Slots
#

Name Description
selectAll
#
Scoped slot for implementing select all functionality
default
#
For KListboxOption(s)