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 currently defaults to multi selection and does not yet support single selection or grouped options (see developer notes above).

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

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.

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.

Related
#

Props
#

Name Description Type Default Required
id
#
Unique listbox ID
 string — true
value
#
Array of currently selected option values
 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
 object — true

Slots
#

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