CascadeSelect

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

Import#


import { CascadeSelect } from 'primereact/cascadeselect';

Basic#

CascadeSelect requires a value to bind and a collection of arbitrary objects with a nested hierarchy. optionGroupLabelis used for the text of a category and optionGroupChildren is to define the children of the category. Note that order of the optionGroupChildrenmatters and it should correspond to the data hierarchy.

Select a City


<CascadeSelect value={selectedCity} options={countries} optionLabel={"cname"} optionGroupLabel={"name"} optionGroupChildren={['states', 'cities']} style={{minWidth: '14rem'}} placeholder={"Select a City"} onChange={event => setSelectedCity(event.value)}/>

Float Label#

A floating label is implemented by wrapping the input and the label inside a container having .p-float-label style class.

p-emptylabel

Float Label


<CascadeSelect value={selectedCity} options={countries} optionLabel={"cname"} optionGroupLabel={"name"} optionGroupChildren={['states', 'cities']} style={{minWidth: '14rem'}} onChange={event => setSelectedCity(event.value)}/>
<label htmlFor="cascadeselect">Float Label</label>

Invalid#

Invalid State

p-emptylabel


<CascadeSelect value={selectedCity} options={countries} optionLabel={"cname"} optionGroupLabel={"name"} optionGroupChildren={['states', 'cities']} style={{minWidth: '14rem'}} onChange={event => setSelectedCity(event.value)}/>
<label htmlFor="cascadeselect">Invalid State</label>

Disabled#

disabled prop prevents an input from being editable.

Disabled


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

Template#

Content of an item can be customized with the itemTemplate prop.

Select a City


<CascadeSelect value={selectedCity} options={countries}  optionLabel={"cname"} optionGroupLabel={"name"} optionGroupChildren={['states', 'cities']} style={{minWidth: '14rem'}} placeholder={"Select a City"} onChange={event => setSelectedCity(event.value)} itemTemplate={countryOptionTemplate}/>

Form#

Compatibility with popular React form libraries.

Formik#

Formik is a popular library for handling forms in React.


<Toast ref={toast} />
<CascadeSelect
    inputId="cc_city"
    name="city"
    value={formik.values.city}
    options={countries}
    optionLabel={'cname'}
    optionGroupLabel={'name'}
    optionGroupChildren={['states', 'cities']}
    style={{ minWidth: '14rem' }}
    placeholder={'Select a City'}
    onChange={(e) => {
        formik.setFieldValue('city', e.value);
    }}
/>
{getFormErrorMessage('city')}
<Button type="submit" label="Submit" />

Hook Form#

React Hook Form is another popular React library to handle forms.


<Toast ref={toast} />
<Controller
    name="city"
    control={control}
    rules={{ required: 'City is required.' }}
    render={({ field }) => (
        <CascadeSelect
            id={field.name}
            name="city"
            value={field.value}
            options={countries}
            optionLabel={'cname'}
            optionGroupLabel={'name'}
            optionGroupChildren={['states', 'cities']}
            style={{ minWidth: '14rem' }}
            placeholder={'Select a City'}
            onChange={(e) => field.onChange(e.value)}
        />
    )}
/>
{getFormErrorMessage('city')}
<Button type="submit" label="Submit" />

Style#

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.

Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

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.

API#

Visit the API documentation for detailed information about all the properties, events and methods of the component.

CascadeSelect