--- 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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/listbox_role) and implements the W3C ARIA APG [Listbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/). Combine it with the [Field](/components/Field) component to access all functionalities.
## Examples
## Listbox Component > Listbox is used to select one or more values from a list of items. ```html ``` ### 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. ```html ``` ### 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](https://github.com/oruga-ui/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](https://github.com/oruga-ui/theme-oruga/tree/main/src/assets/scss/components/_listbox.scss)
> Current theme ➜ _[Bulma](https://github.com/oruga-ui/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](https://github.com/oruga-ui/theme-bulma/tree/main/src/assets/scss/components/_listbox.scss)
> Current theme ➜ _[Bootstrap](https://github.com/oruga-ui/theme-bootstrap)_ | SASS Variable | Default | | ------------- | ------- | See ➜ 📄 [SCSS file](https://github.com/oruga-ui/theme-bootstrap/tree/main/src/assets/scss/components/_listbox.scss)