CascadeSelect

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

Basic

Select a City

Templating

Select a City

Import via Module


import { CascadeSelect } from 'primereact/cascadeselect';

Import via CDN


<script src="https://unpkg.com/primereact/core/core.min.js"></script>
<script src="https://unpkg.com/primereact/cascadeselect/cascadeselect.min.js"></script>

Getting Started

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.


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


const countries = [
    {
        name: 'Australia',
        code: 'AU',
        states: [
            {
                name: 'New South Wales',
                cities: [
                    {cname: 'Sydney', code: 'A-SY'},
                    {cname: 'Newcastle', code: 'A-NE'},
                    {cname: 'Wollongong', code: 'A-WO'}
                ]
            },
            {
                name: 'Queensland',
                cities: [
                    {cname: 'Brisbane', code: 'A-BR'},
                    {cname: 'Townsville', code: 'A-TO'}
                ]
            },

        ]
    },
    {
        name: 'Canada',
        code: 'CA',
        states: [
            {
                name: 'Quebec',
                cities: [
                    {cname: 'Montreal', code: 'C-MO'},
                    {cname: 'Quebec City', code: 'C-QU'}
                ]
            },
            {
                name: 'Ontario',
                cities: [
                    {cname: 'Ottawa', code: 'C-OT'},
                    {cname: 'Toronto', code: 'C-TO'}
                ]
            },

        ]
    },
    {
        name: 'United States',
        code: 'US',
        states: [
            {
                name: 'California',
                cities: [
                    {cname: 'Los Angeles', code: 'US-LA'},
                    {cname: 'San Diego', code: 'US-SD'},
                    {cname: 'San Francisco', code: 'US-SF'}
                ]
            },
            {
                name: 'Florida',
                cities: [
                    {cname: 'Jacksonville', code: 'US-JA'},
                    {cname: 'Miami', code: 'US-MI'},
                    {cname: 'Tampa', code: 'US-TA'},
                    {cname: 'Orlando', code: 'US-OR'}
                ]
            },
            {
                name: 'Texas',
                cities: [
                    {cname: 'Austin', code: 'US-AU'},
                    {cname: 'Dallas', code: 'US-DA'},
                    {cname: 'Houston', code: 'US-HO'}
                ]
            }
        ]
    }
]

Templating

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


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


const countryOptionTemplate = (option) => {
    return (
        <div className="country-item">
            {option.states && <img alt={option.name} src="images/flag/flag_placeholder.png" onError={(e) => e.target.src='https://www.primefaces.org/wp-content/uploads/2020/05/placeholder.png'}
                                   className={`flag flag-${option.code.toLowerCase()}`} />}
            {option.cities && <i className="pi pi-compass mr-2"/>}
            {option.cname && <i className="pi pi-map-marker mr-2"/>}
            <span>{option.cname || option.name}</span>
        </div>
    );
}

Properties

Any valid attribute is passed to the root element implicitly, extended properties are as follows;

Name	Type	Default	Description
id	string	null	Unique identifier of the element.
style	object	null	Inline style of the component.
className	string	null	Style class of the component.
options	array	null	An array of selectitems to display as the available options.
optionLabel	string	null	Property name or getter function to use as the label of an option.
optionValue	string	null	Property name or getter function to use as the value of an option, defaults to the option itself when not defined.
optionGroupLabel	string	null	Property name or getter function to use as the label of an option group.
optionGroupChildren	string	null	Property name or getter function to retrieve the items of a group.
placeholder	string	null	Default text to display when no option is selected.
disabled	boolean	false	When present, it specifies that the component should be disabled.
dataKey	string	null	A property to uniquely identify an option.
tabIndex	number	null	Index of the element in tabbing order.
inputId	string	null	Identifier of the underlying input element.
ariaLabelledBy	string	null	Establishes relationships between the component and label(s) where its value should be one or more element IDs.
appendTo	DOM element \| string	document.body	DOM element instance where the overlay panel should be mounted. Valid values are any DOM Element and 'self'. The self value is used to render a component where it is located.
itemTemplate	any	null	The template of items.
transitionOptions	object	null	The properties of CSSTransition can be customized, except for "nodeRef" and "in" properties.
dropdownIcon	string	pi pi-chevron-down	Icon class of the dropdown icon.

Events

Name	Parameters	Description
onChange	event.originalEvent: Original event event.value: Value of the checkbox	Callback to invoke on value change
onGroupChange	event: Browser event.	Callback to invoke when a group changes.
onBeforeShow	-	Callback to invoke before the overlay is shown.
onBeforeHide	-	Callback to invoke before the overlay is hidden.
onShow	-	Callback to invoke when the overlay is shown.
onHide	-	Callback to invoke when the overlay is hidden.

Styling

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.