import Listbox from 'primevue/listbox';
Listbox requires a value to bind and a collection of arbitrary objects along with the optionLabel property to specify the label property of the option.
<Listbox v-model="selectedCity" :options="cities" optionLabel="name" />
data() {
return {
selectedCity: null,
cities: [
{name: 'New York', code: 'NY'},
{name: 'Rome', code: 'RM'},
{name: 'London', code: 'LDN'},
{name: 'Istanbul', code: 'IST'},
{name: 'Paris', code: 'PRS'}
]
}
}
Listbox allows selection of either single or multiple items. In single case, model should be a single object reference whereas in multiple case should be an array. Multiple items can either be selected using metaKey or toggled individually depending on the value of metaKeySelection property value which is true by default. On touch enabled devices metaKeySelection is turned off automatically.
<Listbox v-model="selectedCity" :options="cities" optionLabel="name" :multiple="true"/>
Options groups are specified with the optionGroupLabel and optionGroupChildren properties.
export default {
data() {
return {
selectedGroupedCity: null,
groupedCities: [{
label: 'Germany', code: 'DE',
items: [
{label: 'Berlin', value: 'Berlin'},
{label: 'Frankfurt', value: 'Frankfurt'},
{label: 'Hamburg', value: 'Hamburg'},
{label: 'Munich', value: 'Munich'}
]
},
{
label: 'USA', code: 'US',
items: [
{label: 'Chicago', value: 'Chicago'},
{label: 'Los Angeles', value: 'Los Angeles'},
{label: 'New York', value: 'New York'},
{label: 'San Francisco', value: 'San Francisco'}
]
},
{
label: 'Japan', code: 'JP',
items: [
{label: 'Kyoto', value: 'Kyoto'},
{label: 'Osaka', value: 'Osaka'},
{label: 'Tokyo', value: 'Tokyo'},
{label: 'Yokohama', value: 'Yokohama'}
]
}]
}
}
}
<Listbox v-model="selectedGroupedCity" :options="groupedCities"
optionLabel="label" optionGroupLabel="label" optionGroupChildren="items">
</Listbox>
Filtering allows searching items in the list using an input field at the header. In order to use filtering, enable filter property. By default, optionLabel is used when searching and filterFields can be used to customize the fields being utilized. Furthermore, filterMatchMode is available to define the search algorithm. Valid values are "contains" (default), "startsWith" and "endsWith".
<Listbox v-model="selectedCity" :options="cities" optionLabel="name" :filter="true"/>
Label of an option is used as the display text of an item by default, for custom content support define an option template that gets the option instance as a parameter. In addition optiongroup, header, footer, emptyfilter and empty slots are provided for further customization.
<Listbox v-model="selectedCars" :options="cars" :multiple="true" :filter="true" optionLabel="brand" listStyle="max-height:250px" style="width:15em">
<template #option="slotProps">
<div>
<img :alt="slotProps.option.brand" :src="'demo/images/car/' + slotProps.option.brand + '.png'" />
<span>{{slotProps.option.brand}}</span>
</div>
</template>
</Listbox>
Any property as style and class are passed to the main container element. Following are the additional properties to configure the component.
| Name | Type | Default | Description |
|---|---|---|---|
| modelValue | any | null | Value of the component. |
| options | array | null | An array of selectitems to display as the available options. |
| optionLabel | string | null | Property name or getter function to use as the label of an option. |
| optionValue | string | null | Property name or getter function to use as the value of an option, defaults to the option itself when not defined. |
| optionDisabled | boolean | null | Property name or getter function to use as the disabled flag of an option, defaults to false when not defined. |
| optionGroupLabel | string | null | Property name or getter function to use as the label of an option group. |
| optionGroupChildren | string | null | Property name or getter function that refers to the children options of option group. |
| listStyle | string | null | Inline style of inner list element. |
| disabled | boolean | false | When specified, disables the component. |
| dataKey | string | null | A property to uniquely identify an option. |
| multiple | boolean | false | When specified, allows selecting multiple values. |
| metaKeySelection | boolean | true | Defines how multiple items can be selected, when true metaKey needs to be pressed to select or unselect an item and when set to false selection of each item can be toggled individually. On touch enabled devices, metaKeySelection is turned off automatically. |
| filter | boolean | false | When specified, displays a filter input at header. |
| filterPlaceholder | string | null | Placeholder text to show when filter input is empty. |
| filterLocale | string | undefined | Locale to use in filtering. The default locale is the host environment's current locale. |
| filterMatchMode | string | contains | Defines the filtering algorithm to use when searching the options. Valid values are "contains" (default), "startsWith" and "endsWith" |
| filterFields | array | null | Fields used when filtering the options, defaults to optionLabel. |
| emptyFilterMessage | string | No results found | Text to display when filtering does not return any results. Defaults to value from PrimeVue locale configuration. |
| emptyMessage | string | No results found | Text to display when there are no options available. Defaults to value from PrimeVue locale configuration. |
| virtualScrollerOptions | object | null | Whether to use the virtualScroller feature. The properties of |
| Name | Parameters | Description |
|---|---|---|
| change | event.originalEvent: Original event event.value: Selected option value |
Callback to invoke on value change. |
| filter | event.originalEvent: Original event event.value: Filter value |
Callback to invoke on filter input. |
| Name | Parameters |
|---|---|
| option | option: Option instance index: Index of the option |
| optiongroup | option: OptionGroup instance index: Index of the option group |
| header | value: Value of the component options: Displayed options |
| footer | value: Value of the component options: Displayed options |
| emptyfilter | - |
| empty | - |
Following is the list of structural style classes, for theming classes visit
| Name | Element |
|---|---|
| p-listbox | Main container element. |
| p-listbox-header | Header element. |
| p-listbox-list-wrapper | Container of list element. |
| p-listbox-list | List element. |
| p-listbox-item | An item in the list element. |
None.