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" />
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" />
</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 items-center gap-2">
<img
src="https://primefaces.org/cdn/primeng/images/demo/flag/flag_placeholder.png"
*ngIf="option.states"
[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>
Loading state can be used loading property.
<p-cascadeselect
[loading]="true"
[style]="{ minWidth: '14rem' }"
placeholder="Loading..." />
A floating label appears on top of the input field when focused. Visit FloatLabel documentation for more information.
<p-floatlabel>
<p-cascadeselect
inputId="cs-city"
[(ngModel)]="selectedCity"
[options]="countries"
optionLabel="cname"
optionGroupLabel="name"
[optionGroupChildren]="['states', 'cities']"
[style]="{ minWidth: '14rem' }"
placeholder="Select a City" />
<label for="cs-city">City</label>
</p-floatlabel>
Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.
<p-cascadeselect
[(ngModel)]="selectedCity"
variant="filled"
[options]="countries"
optionLabel="cname"
optionGroupLabel="name"
[optionGroupChildren]="['states', 'cities']"
[style]="{ minWidth: '14rem' }"
placeholder="Select a City" />
Invalid state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.
<p-cascadeselect
class="ng-invalid ng-dirty"
[(ngModel)]="selectedCity"
[options]="countries"
optionLabel="cname"
optionGroupLabel="name"
[optionGroupChildren]="['states', 'cities']"
[style]="{ minWidth: '14rem' }"
placeholder="Select a City" />
When disabled is present, the element cannot be edited and focused.
<p-cascadeselect
[disabled]="true"
placeholder="Disabled"
[style]="{ minWidth: '14rem' }" />
Value to describe the component can either be provided with ariaLabelledBy or ariaLabel 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>
<p-cascadeselect ariaLabelledBy="dd1"/>
<p-cascadeselect ariaLabel="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. |
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. |