import CascadeSelect from 'primevue/cascadeselect';
<script src="https://unpkg.com/primevue@^3/core/core.min.js"></script>
<script src="https://unpkg.com/primevue@^3/cascadeselect/cascadeselect.min.js"></script>
CascadeSelect requires a value to bind and a collection of arbitrary objects with a nested hierarchy. optionGroupLabel is used for the text of a category and optionGroupChildren is to define the children of the category. Note that order of the optionGroupChildren matters and it should correspond to the data hierarchy.
<CascadeSelect v-model="selectedCity" :options="countries" optionLabel="cname" optionGroupLabel="name"
:optionGroupChildren="['states', 'cities']" style="minWidth: 14rem" >
data() {
return {
selectedCity: null,
countries: [
{
name: 'Australia',
code: 'AU',
states: [
{
name: 'New South Wales',
cities: [
{cname: 'Sydney', code: 'A-SY'},
{cname: 'Newcastle', code: 'A-NE'},
{cname: 'Wollongong', code: 'A-WO'}
]
},
{
name: 'Queensland',
cities: [
{cname: 'Brisbane', code: 'A-BR'},
{cname: 'Townsville', code: 'A-TO'}
]
},
]
},
{
name: 'Canada',
code: 'CA',
states: [
{
name: 'Quebec',
cities: [
{cname: 'Montreal', code: 'C-MO'},
{cname: 'Quebec City', code: 'C-QU'}
]
},
{
name: 'Ontario',
cities: [
{cname: 'Ottawa', code: 'C-OT'},
{cname: 'Toronto', code: 'C-TO'}
]
},
]
},
{
name: 'United States',
code: 'US',
states: [
{
name: 'California',
cities: [
{cname: 'Los Angeles', code: 'US-LA'},
{cname: 'San Diego', code: 'US-SD'},
{cname: 'San Francisco', code: 'US-SF'}
]
},
{
name: 'Florida',
cities: [
{cname: 'Jacksonville', code: 'US-JA'},
{cname: 'Miami', code: 'US-MI'},
{cname: 'Tampa', code: 'US-TA'},
{cname: 'Orlando', code: 'US-OR'}
]
},
{
name: 'Texas',
cities: [
{cname: 'Austin', code: 'US-AU'},
{cname: 'Dallas', code: 'US-DA'},
{cname: 'Houston', code: 'US-HO'}
]
}
]
}
]
}
}
Content of an item can be customized with the option template.
<CascadeSelect v-model="selectedCity" :options="countries" optionLabel="cname" optionGroupLabel="name"
:optionGroupChildren="['states', 'cities']" style="minWidth: 14rem">
<template #option="slotProps">
<div class="country-item">
<img src="../../assets/images/flag_placeholder.png" :class="'flag flag-' + slotProps.option.code.toLowerCase()" v-if="slotProps.option.states" />
<i class="pi pi-compass mr-2" v-if="slotProps.option.cities"></i>
<i class="pi pi-map-marker mr-2" v-if="slotProps.option.cname"></i>
<span>{{slotProps.option.cname || slotProps.option.name}}</span>
</div>
</template>
</CascadeSelect>
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 | function | null | Property name or getter function to use as the label of an option. |
| optionValue | string | function | null | Property name or getter function to use as the value of an option, defaults to the option itself when not defined. |
| optionDisabled | string | function | null | Property name or getter function to use as the disabled flag of an option, defaults to false when not defined. |
| optionGroupLabel | string | function | null | Property name or getter function to use as the label of an option group. |
| optionGroupChildren | array | function | null | Property name or getter function to retrieve the items of a group. |
| placeholder | string | null | Default text to display when no option is selected. |
| disabled | boolean | false | When present, it specifies that the component should be disabled. |
| dataKey | string | null | A property to uniquely identify an option. |
| inputId | string | null | Identifier of the underlying input element. |
| inputStyle | any | null | Inline style of the input field. |
| inputClass | string | null | Style class of the input field. |
| inputProps | object | null | Uses to pass all properties of the HTMLInputElement/HTMLSpanElement to the focusable input element inside the component. |
| panelStyle | any | null | Inline style of the overlay panel. |
| panelClass | string | null | Style class of the overlay panel. |
| panelProps | object | null | Uses to pass all properties of the HTMLDivElement to the overlay panel. |
| appendTo | string | body | A valid query selector or an HTMLElement to specify where the overlay gets attached. Special keywords are "body" for document body and "self" for the element itself. |
| loading | boolean | false | Whether the dropdown is in loading state. |
| loadingIcon | string | pi pi-spinner pi-spin | Icon to display in loading state. |
| autoOptionFocus | boolean | true | Whether to focus on the first visible or selected element when the overlay panel is shown. |
| selectOnFocus | boolean | false | When enabled, the focused option is selected/opened. |
| searchLocale | string | undefined | Locale to use in searching. The default locale is the host environment's current locale. |
| searchMessage | string | {0} results are available | Text to be displayed in hidden accessible field when filtering returns any results. Defaults to value from PrimeVue locale configuration. |
| selectionMessage | string | {0} items selected | Text to be displayed in hidden accessible field when options are selected. Defaults to value from PrimeVue locale configuration. |
| emptySelectionMessage | string | No selected item | Text to be displayed in hidden accessible field when any option is not selected. Defaults to value from PrimeVue locale configuration. |
| emptySearchMessage | string | No results found | Text to be displayed when filtering does not return any results. Defaults to value from PrimeVue locale configuration. |
| emptyMessage | string | No available options | Text to be displayed when there are no options available. Defaults to value from PrimeVue locale configuration. |
| tabindex | number | 0 | Index of the element in tabbing order. |
| aria-label | string | null | Defines a string value that labels an interactive element. |
| aria-labelledby | string | null | Establishes relationships between the component and label(s) where its value should be one or more element IDs. |
| Name | Parameters | Description |
|---|---|---|
| change |
event.originalEvent: Original event event.value: Selected option value |
Callback to invoke on value change. |
| focus | event | Callback to invoke when the component receives focus. |
| blur | event | Callback to invoke when the component loses focus. |
| click | event | Callback to invoke on click. |
| group-change |
event.originalEvent: Original event event.value: Selected option group |
Callback to invoke when a group changes. |
| before-show | - | Callback to invoke before the overlay is shown. |
| before-hide | - | Callback to invoke before the overlay is hidden. |
| show | - | Callback to invoke when the overlay is shown. |
| hide | - | Callback to invoke when the overlay is hidden. |
| Name | Parameters |
|---|---|
| value |
value: Value of the component placeholder: Placeholder text to show |
| option | option: Option instance |
| indicator | - |
Following is the list of structural style classes, for theming classes visit
| Name | Element |
|---|---|
| p-cascadeselect | Container element. |
| p-cascadeselect-label | Element to display label of selected option. |
| p-cascadeselect-trigger | Icon element. |
| p-cascadeselect-panel | Icon element. |
| p-cascadeselect-items-wrapper | Wrapper element of items list. |
| p-cascadeselect-items | List element of items. |
| p-cascadeselect-item | An item in the list. |
| p-overlay-open | Container element when overlay is visible. |
Value to describe the component can either be provided with aria-labelledby or aria-label props. The cascadeselect element has a combobox role in addition to aria-haspopup and aria-expanded attributes. The relation between the combobox and the popup is created with aria-controls that refers to the id of the popup.
The popup list has an id that refers to the aria-controls attribute of the combobox element and uses tree as the role. Each list item has a treeitem role along with aria-label, aria-selected and aria-expanded attributes. The container element of a treenode has the group role. The aria-setsize, aria-posinset and aria-level attributes are calculated implicitly and added to each treeitem.
<span id="dd1">Options</span>
<CascadeSelect aria-labelledby="dd1" />
<CascadeSelect aria-label="Options" />
| Key | Function |
|---|---|
| tab | Moves focus to the cascadeselect element. |
| space | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. |
| enter | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. |
| down arrow | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. |
| up arrow | Opens the popup and moves visual focus to the selected option, if there is none then last option receives the focus. |
| any printable character | Opens the popup and moves focus to the option whose label starts with the characters being typed, if there is none then first option receives the focus. |
| Key | Function |
|---|---|
| tab | Hides the popup and moves focus to the next tabbable element. If there is none, the focusable option is selected and the overlay is closed then moves focus to next element in page. |
| shift + tab | Hides the popup and moves focus to the previous tabbable element. |
| enter | Selects the focused option and closes the popup. |
| space | Selects the focused option and closes the popup. |
| escape | Closes the popup, moves focus to the cascadeselect element. |
| down arrow | Moves focus to the next option. |
| up arrow | Moves focus to the previous option. |
| alt + up arrow | Selects the focused option and closes the popup, then moves focus to the cascadeselect element. |
| right arrow | If option is closed, opens the option otherwise moves focus to the first child option. |
| left arrow | If option is open, closes the option otherwise moves focus to the parent option. |
| home | Moves input cursor at the end, if not then moves focus to the first option. |
| end | Moves input cursor at the beginning, if not then moves focus to the last option. |
| any printable character | Moves focus to the option whose label starts with the characters being typed. |
None.