CascadeSelect

CascadeSelect displays a nested structure of options.

Import #


import { CascadeSelectModule } from 'primeng/cascadeselect';

Basic #

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.

Select a City 3 results are available 

<p-cascadeSelect 
    [(ngModel)]="selectedCity" 
    [options]="countries" 
    optionLabel="cname" 
    optionGroupLabel="name" 
    [optionGroupChildren]="['states', 'cities']" 
    [style]="{ minWidth: '14rem' }"
    placeholder="Select a City" />

Reactive Forms #

CascadeSelect can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.

Select a City 3 results are available 

<form [formGroup]="formGroup">
    <p-cascadeSelect 
        formControlName="selectedCity" 
        [options]="countries" 
        optionLabel="cname" 
        optionGroupLabel="name" 
        [optionGroupChildren]="['states', 'cities']" 
        [style]="{ minWidth: '14rem' }"
        placeholder="Select a City" />
</form>

Template #

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.

Select a City 3 results are available 

<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 
                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 #

Loading state can be used loading property.

Loading... No results found 

<p-cascadeSelect 
    [loading]="true" 
    [style]="{ minWidth: '14rem' }"
    placeholder="Loading..." />

Float Label #

A floating label appears on top of the input field when focused. Visit FloatLabel documentation for more information.

Select a City 3 results are available 

<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>

Filled #

Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.

Select a City 3 results are available 

<p-cascadeSelect 
    [(ngModel)]="selectedCity" 
    variant="filled"
    [options]="countries" 
    optionLabel="cname" 
    optionGroupLabel="name" 
    [optionGroupChildren]="['states', 'cities']" 
    [style]="{ minWidth: '14rem' }"
    placeholder="Select a City" />

Invalid #

Invalid state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.

Select a City 3 results are available 

<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" />

Disabled #

When disabled is present, the element cannot be edited and focused.

Disabled No results found 

<p-cascadeSelect
    [disabled]="true" 
    placeholder="Disabled" 
    [style]="{ minWidth: '14rem' }" />

Style #

Following is the list of structural style classes, for theming classes visit theming page.

NameElement
p-cascadeselectContainer element.
p-cascadeselect-labelElement to display label of selected option.
p-cascadeselect-triggerIcon element.
p-cascadeselect-panelIcon element.
p-cascadeselect-items-wrapperWrapper element of items list.
p-cascadeselect-itemsList element of items.
p-cascadeselect-itemAn item in the list.

Accessibility #

Screen Reader

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"/>

Closed State Keyboard Support

KeyFunction
tabMoves focus to the cascadeselect element.
spaceOpens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.
down arrowOpens the popup and moves visual focus to the selected option, if there is none then first option receives the focus.

Popup Keyboard Support

KeyFunction
tabHides the popup and moves focus to the next tabbable element.
shift + tabHides the popup and moves focus to the previous tabbable element.
enterSelects the focused option and closes the popup.
spaceSelects the focused option and closes the popup.
escapeCloses the popup, moves focus to the cascadeselect element.
down arrowMoves focus to the next option.
up arrowMoves focus to the previous option.
right arrowIf option is closed, opens the option otherwise moves focus to the first child option.
left arrowIf option is open, closes the option otherwise moves focus to the parent option.
PrimeNG 17.18.12 by PrimeTek