CascadeSelect displays a nested structure of options.
import { CascadeSelectModule } from 'primeng/cascadeselect';
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.
<p-cascadeSelect [(ngModel)]="selectedCity" [options]="countries" optionLabel="cname" optionGroupLabel="name" [optionGroupChildren]="['states', 'cities']" [style]="{ minWidth: '14rem' }" placeholder="Select a City"></p-cascadeSelect>
CascadeSelect can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.
<form [formGroup]="formGroup">
<p-cascadeSelect formControlName="selectedCity" [options]="countries" optionLabel="cname" optionGroupLabel="name" [optionGroupChildren]="['states', 'cities']" [style]="{ minWidth: '14rem' }" placeholder="Select a City"></p-cascadeSelect>
</form>
CascadeSelect is used as a controlled component with ngModel property along with an options collection. To define the label of a group optionGroupLabel property is needed and also optionGroupChildren is required to define the property that refers to the children of a group. Note that order of the optionGroupChildren matters as it should correspond to the data hierarchy.
<p-cascadeSelect [(ngModel)]="selectedCity" [options]="countries" optionLabel="cname" optionGroupLabel="name" [optionGroupChildren]="['states', 'cities']" [style]="{ minWidth: '14rem' }" placeholder="Select a City">
<ng-template pTemplate="option" let-option>
<div class="flex align-items-center gap-2">
<img *ngIf="option.states" src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png" [class]="'flag flag-' + option.code.toLowerCase()" />
<i class="pi pi-compass mr-2" *ngIf="option.cities"></i>
<i class="pi pi-map-marker mr-2" *ngIf="option.cname"></i>
<span>{{ option.cname || option.name }}</span>
</div>
</ng-template>
</p-cascadeSelect>
Following is the list of structural style classes, for theming classes visit theming page.
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. |
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.
If filtering is enabled, filterInputProps can be defined to give aria-* props to the filter input element.
<span id="dd1">Options</span>
<p-cascadeSelect aria-labelledby="dd1"></p-cascadeSelect>
<p-cascadeSelect aria-label="Options"></p-cascadeSelect>
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. |
down arrow | Opens the popup and moves visual focus to the selected option, if there is none then first option receives the focus. |
Key | Function |
---|---|
tab | Hides the popup and moves focus to the next tabbable element. |
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. |
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. |
API defines helper props, events and others for the PrimeNG CascadeSelect module.
Name | Type | Default | Description |
---|---|---|---|
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. |
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 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. |
tabindex | number | null | Index of the element in tabbing order. |
inputId | string | null | Identifier of the underlying input element. |
ariaLabelledBy | string | null | Establishes relationships between the component and label(s) where its value should be one or more element IDs. |
appendTo | string | null | Id of the element or "body" for document where the overlay should be appended to. |
style | object | null | Inline style of the component. |
panelStyle | object | null | Inline style of the overlay panel. |
styleClass | string | null | Style class of the component. |
panelStyleClass | string | null | Style class of the overlay panel. |
inputLabel | string | null | Label of the input for accessibility. |
ariaLabel | string | null | Defines a string that labels the input for accessibility. |
ariaLabelledBy | string | null | Specifies one or more IDs in the DOM that labels the input field. |
showClear | boolean | false | When enabled, a clear icon is displayed to clear the value. |
overlayOptions | OverlayOptions | null | Whether to use overlay API feature. The properties of overlay API can be used like an object in it. |
Name | Parameters | Description |
---|---|---|
onChange | event.originalEvent: Original event event.value: Selected option value | Callback to invoke on value change. |
onGroupChange | event.originalEvent: Original event event.value: Selected option group | Callback to invoke when a group changes. |
onBeforeShow | - | Callback to invoke before the overlay is shown. |
onBeforeHide | - | Callback to invoke before the overlay is hidden. |
onShow | - | Callback to invoke when the overlay is shown. |
onHide | - | Callback to invoke when the overlay is hidden. |
onClear | - | Callback to invoke when input field is cleared. |
Name | Parameters |
---|---|
value | $implicit: value |
option | $implicit: option |
triggericon | - |
clearicon | - |
optiongroupicon | - |