File: cascadeselect.md | Updated: 11/15/2025
Introducing PrimeReact v11 Alpha 🥁Learn More
SearchK
10.9.7
FEATURES
API
THEMING
PASS THROUGH
CascadeSelect is a form component to select a value from a nested structure of options.
Import#
import { CascadeSelect } from 'primereact/cascadeselect';
Copy
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' }} />
Copy
Loading State#
Loading state can be used loading property.
Loading...
<CascadeSelect loading placeholder="Loading..." className="w-full md:w-14rem" breakpoint="767px" style={{ minWidth: '14rem' }} />
Copy
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' }} />
Copy
Clear Icon#
When showClear is enabled, a clear icon is added to reset the CascadeSelect.
Select a City
<CascadeSelect value={selectedCity} showClear 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' }} />
Copy
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>
Copy
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' }} />
Copy
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' }} />
Copy
Disabled#
When disabled is present, the element cannot be edited and focused.
Disabled
<CascadeSelect disabled placeholder="Disabled" style={{ minWidth: '14rem' }} />
Copy
Accessibility#
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" />
Copy
| 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. |
Import
Basic
Loading State
Template
Clear Icon
Float Label
Filled
Invalid
Disabled
Accessibility
PrimeReact 10.9.7 by PrimeTek