Cascader

import { Cascader } from '@enmovil/ui-design-system';

A select for choosing a value from a hierarchy, such as region, state and city, by drilling down level by level. It supports search, selecting several values, and choosing a parent level as the value.

Properties

Property	Type	Required	Default	Allowed values	Description
multiple	boolean	No	—	—	Lets the user check several values, each shown as a tag. Tags that do not fit collapse into "+ N more", with the rest listed in a tooltip.
size	string	No	'middle'	'small', 'middle', 'large'	Height of the select box: small (28px), middle (34px) or large (40px), as in Select. Defaults to middle.
disabled	boolean	No	—	—	Greys out the cascader and stops it from opening.
options	OptionType[]	No	—	—	The hierarchy to choose from. Each option has a value and label, and optionally children, disabled, and isLeaf: false for children loaded later with loadData.
status	string	No	—	'', 'error', 'warning'	Validation state of the select box: error or warning.
style	CSSProperties	No	—	—	Inline styles of the select box, for example its width.
defaultValue	ValueType<Required<OptionType>, keyof OptionType>[] | ValueType<Required<OptionType>, keyof OptionType>[][]	No	—	—	Initially selected path when uncontrolled, as the values from the top level down, for example ["south", "karnataka", "bengaluru"]. With multiple, an array of such paths.
changeOnSelect	boolean	No	—	—	Lets any level be the value, not only a leaf, so the value changes at each level the user clicks.
showCheckedStrategy	string	No	—	'SHOW_PARENT', 'SHOW_CHILD'	With multiple, which checked items appear as tags: SHOW_PARENT (the default) shows a parent in place of its children once all are checked, SHOW_CHILD shows each checked leaf.
expandTrigger	string	No	—	'hover', 'click'	How sub-menus open: click (the default) or hover.
showSearch	boolean | ShowSearchType<OptionType, keyof OptionType>	No	—	—	Adds a search box that filters every path by the typed text.
placeholder	ReactNode	No	—	—	Text shown while nothing is selected.
allowClear	boolean | { clearIcon?: RenderNode; }	No	—	—	Shows a clear icon over a selected value. On by default; set false to hide it.

Other attributes

Cascader passes 121 further attributes through to the underlying element. They aren't part of the supported API and may change between releases, so use only the properties listed on this page.

Events

Name	Signature	When it fires
onDropdownVisibleChange	((visible: boolean) => void)	Fires when the menus open or close.
onFocus	FocusEventHandler<HTMLElement>	Fires when the cascader receives focus.
onBlur	FocusEventHandler<HTMLElement>	Fires when the cascader loses focus.
onChange	((value: ValueType<Required<OptionType>, keyof OptionType>[], selectOptions: OptionType[]) => void) | ((value: ValueType<Required<OptionType>, keyof OptionType>[][], selectOptions: OptionType[][]) => void)	Fires when the selected path changes, with the value path and the matching options.
onSearch	((value: string) => void)	Fires as the user types in the search box. Requires showSearch.
displayRender	((label: string[], selectedOptions?: OptionType[]) => ReactNode)	Formats the selected path shown in the box. Called with the labels of the path; without it they are joined with " / ".

Children

Cascader does not accept children.

Variants

Loading examples…

Playground

Change the controls to see how the properties affect the component. Values the controls don't cover come from the Default example.

Loading playground…

Storybook

Open Cascader in Storybook to try every story with the full set of controls.