Listbox.md

sidebarDepth	2

Listbox

The Listbox component presents a list of options and allows a user to select one or more of them. The component uses the ARIA listbox role and implements the W3C ARIA APG Listbox Pattern. Combine it with the Field component to access all functionalities.

Examples

Listbox Component

Listbox is used to select one or more values from a list of items.

<o-listbox></o-listbox>

Props

Prop name	Description	Type	Values	Default
animation	Custom animation (transition name)	string	-	From config: listbox: {   animation: "fade" }
ariaLabel	Defines a string value that labels an interactive element.	string	-
ariaLabelledby	Identifier of the underlying input element.	string	-
backendFiltering	Items won't be filtered on clientside, use the filter event to filter in your backend	boolean	-	false
disabled	Interaction is disabled	boolean	-	false
emptyLabel	A label which is displayed when no options are visible	string	-	From config: listbox: {   emptyLabel: undefined }
filter	Custom filter function to filter the items based on the input value - default is label string comparison	((option: unknown, value: string) => boolean)	-
filterDebounce	Number of milliseconds to delay the filter event	number	-	From config: listbox: {   filterDebounce: 400 }
filterIcon	Icon of the column search input	string	-	From config: listbox: {   filterIcon: undefined }
filterPlaceholder	Placeholder of the column search input	string	-	From config: listbox: {   filterPlaceholder: undefined }
filterable	Enable an additional searchbar below the header	boolean	-	false
iconPack	Icon pack to use	string	mdi, fa, fas and any other custom icon pack	From config: listbox: {   iconPack: undefined }
id	Same as native id. Also pass the id to an wrapping o-field component - default is an uuid.	string	-	useId()
v-model	The selected option value, use v-model to make it two-way binding	string|number|object	-
multiple	Allows multiple selections - converts the modelValue into an array	IsMultiple	-
options	Autocomplete options	ListboxOptions<unknown>	-
override	Override existing theme classes completely	boolean	-
scrollHeight	Height of the listbox, a scrollbar is defined if height of list exceeds this value	number | string	-	From config: listbox: {   scrollHeight: "225" }
selectOnFocus	Select current focused item when focused	boolean	-	false
selectable	Enables item selection	boolean	-	true

Events

Event name	Properties	Description
update:model-value	value unknown | unknown[] - updated modelValue prop	modelValue prop two-way binding
select	value unknown - selected value	on select event - fired before update:modelValue
filter	value string - filter value event Event - native event	on filter change event
focus	event Event - native event	on list focus event
blur	event Event - native event	on list blur event
scroll-start		scrolling inside the list reached the start
scroll-end		scrolling inside the list reached the end

Slots

Name	Description	Bindings
header	Define an additional header
filter	Overridet the filter input	value string - filter input value onChange (input: string, event: Event): void - on filter input change event onKeydown (event: Event): void - on filter input keydown event
default	Define the listbox items here
empty	Define the content to show if the list is empty
footer	Define an additional footer

ListItem Component

An option item used by the listbox component.

<o-list-item></o-list-item>

Props

Prop name	Description	Type	Values	Default
ariaLabel	Defines a string value that labels an interactive element.	string	-
ariaLabelledby	Identifier of the underlying input element.	string	-
disabled	Item is disabled	boolean	-	false
hidden	Define whether the item is visible or not	boolean	-	false
icon	Icon to be shown	string	-
iconPack	Icon pack to use	string	mdi, fa, fas and any other custom icon pack	From config: listbox: {   iconPack: undefined }
iconSize	Icon size	string	small, medium, large	From config: listbox: {   iconSize: undefined }
label	Item label, unnecessary when default slot is used	string	-
override	Override existing theme classes completely	boolean	-
value	Item value (it will be used as v-model of wrapper component) - default is an uuid	string|number|object	-	useId()

Events

Event name	Properties	Description
click	value unknown - value prop data event event - native event	onclick event

Slots

Name	Description	Bindings
default	Override the label, default is label prop	selected boolean - item is selected disabled boolean - item is disabled

Class Inspector

Sass Variables

Current theme ➜ Oruga

SASS Variable	Default
$listbox-disabled-opacity	h.useVar("control-disabled-opacity")
$listbox-background-color	h.useVar("control-background-color")
$listbox-border-color	h.useVar("control-border-color")
$listbox-border-style	solid
$listbox-border-width	h.useVar("control-border-width")
$listbox-border-radius	h.useVar("border-radius")
$listbox-item-padding	h.useVar("control-spacer") calc(h.useVar("control-spacer") * 2)
$listbox-item-color	h.useVar("font-color")
$listbox-item-font-size	h.useVar("font-size")
$listbox-item-font-weight	h.useVar("font-weight")
$listbox-item-line-height	h.useVar("line-height")
$listbox-item-background-color	transparent
$listbox-item-active-color	h.useVar("primary-invert")
$listbox-item-active-background-color	h.useVar("primary")
$listbox-item-hover-background-color	h.useVar("grey-lighter")
$listbox-item-hover-color	h.useVar("font-color")

See ➜ 📄 SCSS file

Current theme ➜ Bulma

SASS Variable	Default
$listbox-disabled-opacity	0.5
$listbox-item-hover-background-color	css.getVar( "panel-block-hover-background-color")
$listbox-item-active-background-color	css.getVar("primary")

See ➜ 📄 SCSS file

Current theme ➜ Bootstrap

SASS Variable	Default

See ➜ 📄 SCSS file