CascadeSelect

CascadeSelect is a form component to select a value from a nested structure of options.

Import#


import { CascadeSelect } from 'primereact/cascadeselect';

Basic#

CascadeSelect is used as a controlled component with value and onChange properties 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


<CascadeSelect value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={countries} 
    optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']}
    className="w-full md:w-14rem" breakpoint="767px" placeholder="Select a City" style={{ minWidth: '14rem' }}  />

Loading State#

Loading state can be used loading property.


<CascadeSelect loading placeholder="Loading..." className="w-full md:w-14rem" breakpoint="767px" style={{ minWidth: '14rem' }} />

Template#

Content of an item is customized with the itemTemplate property that takes an option as a parameter.

Select a City


<CascadeSelect value={selectedCity} onChange={e => setSelectedCity(e.value)} options={countries} 
    optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']} 
    className="w-full md:w-14rem" breakpoint="767px" placeholder="Select a City" itemTemplate={countryOptionTemplate} style={{ minWidth: '14rem' }} />

Float Label#

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

p-emptylabel

City


<FloatLabel>
    <CascadeSelect inputId="cs-city" value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={countries}
        optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']}
        className="w-full md:w-14rem" breakpoint="767px" style={{ minWidth: '14rem' }} />
    <label htmlFor="cs-city">City</label>
</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


<CascadeSelect variant="filled" value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={countries} 
    optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']}
    className="w-full md:w-14rem" breakpoint="767px" placeholder="Select a City" style={{ minWidth: '14rem' }}  />

Invalid#

Invalid state is displayed using the invalid prop to indicate a failed validation. You can use this style when integrating with form validation libraries.

Select a City


<CascadeSelect invalid value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={countries} 
    optionLabel="cname" optionGroupLabel="name" optionGroupChildren={['states', 'cities']}
    className="w-full md:w-14rem" breakpoint="767px" placeholder="Select a City" style={{ minWidth: '14rem' }} />

Disabled#

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

Disabled


<CascadeSelect disabled placeholder="Disabled" style={{ minWidth: '14rem' }} />

Accessibility#

Screen Reader

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>
<CascadeSelect aria-labelledby="dd1" />

<CascadeSelect aria-label="Options" />

Closed State Keyboard Support

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.

Popup Keyboard Support

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.