Cascader
Select a path from hierarchical data with cascading columns
Source
Package
Usage
Cascader lets users select a value from hierarchical data. Picking an option in one column reveals its children in the next column. The value is a path from the root option to the selected one, for example ['asia', 'jp', 'tokyo'].
Demos on this page switch to the flat list layout on small screens:
Cascader with uncontrolled forms
Set name to submit the selected path as one comma-separated string of option values:
Data prop
data is an array of options. Each option must have a unique value across the whole tree, children contains nested options:
Value and onChange
The value is an array of option values or null when nothing is selected. onChange is called with the selected path and the corresponding options:
Change on select
By default, only leaf options can be selected and clicking a parent option expands the next column. Set changeOnSelect to allow selecting any option:
Close on select
By default, the dropdown stays open after a value is selected. Set closeOnSelect to close it when an option without children is selected:
Allow deselect
By default, clicking the selected option again removes the value. Set allowDeselect={false} to disable this behavior:
Expand trigger
Set expandTrigger="hover" to open the next column on hover instead of click. Selecting a leaf still requires a click:
With expandTrigger="hover", the open column stays in place while the cursor moves diagonally toward it. Set safeAreaPolygon={false} to disable this behavior or pass an object with safePolygon options:
Flat list layout
Columns do not fit narrow screens. Set withColumns={false} to render options as a flat list of full paths instead:
Combine withColumns with the use-matches hook to render columns on desktop and the flat list on mobile:
Virtualized dropdown
Use virtualizer for search results and the flat list shown when withColumns={false}. Search for a product to select its full path:
Max displayed levels
Use maxDisplayedLevels to limit the number of columns displayed next to each other. When the limit is exceeded, the first columns are hidden behind a control on the left:
Searchable
Set the searchable prop to allow filtering options. In search mode, the columns are replaced with a flat list of full paths that match the query:
Use the filter prop to customize how paths are matched and renderSearchOption to customize how search results are rendered:
Controlled search value
Use searchValue and onSearchChange props to control the search value:
Nothing found
Set the nothingFoundMessage prop to display a message when no options match the search query:
Display value
The input displays option labels joined by the separator. Use formatValue to fully customize the input label:
Column width
Use columnWidth to set a fixed width for every column and maxDropdownHeight to set the max height of a column:
Custom option rendering
Use the renderOption prop to customize how options are rendered in columns. The function receives the option and its column level:
Check icon
Use the withCheckIcon prop to toggle the check icon on the selected option and checkIconPosition to change its position (left or right):
Disabled options
Set disabled on an option to prevent it from being selected or expanded:
Left and right sections
Cascader supports leftSection and rightSection props the same way as other inputs:
Clearable
Set the clearable prop to display the clear button when a value is selected:
Use the clearSectionMode prop to control how the clear button and rightSection are rendered:
Scrollable columns
A column scrolls when its options are taller than maxDropdownHeight. Use scrollAreaProps to pass props down to the ScrollArea of each column:
Control dropdown opened state
Use dropdownOpened, defaultDropdownOpened, onDropdownOpen and onDropdownClose props to control the dropdown opened state:
Dropdown position
Use comboboxProps to pass props down to the underlying Combobox and Popover. For example, set position to change the dropdown position:
Dropdown offset
Dropdown width
In columns mode the dropdown is sized to the columns. In flat list mode, set the width with comboboxProps={{ width }}:
Dropdown padding
Dropdown shadow
Dropdown animation
Combobox props
You can override Combobox props with comboboxProps. This is useful when you need to change some of the props that are not exposed by Cascader, for example withinPortal:
Change dropdown z-index
Styles API
Use the Styles API to customize Cascader styles:
Component Styles API
Hover or focus a selector to highlight its elements
Left and right sections
Cascader supports leftSection and rightSection props. These sections are rendered with absolute positioning inside the input wrapper. You can use them to display icons, input controls, or any other elements.
You can use the following props to control sections styles and content:
rightSection/leftSection– React node to render on the corresponding side of inputrightSectionWidth/leftSectionWidth– controls the width of the right section and padding on the corresponding side of the input. By default, it is controlled by the componentsizeprop.rightSectionPointerEvents/leftSectionPointerEvents– controls thepointer-eventsproperty of the section. If you want to render a non-interactive element, set it tononeto pass clicks through to the input.
Input props
Cascader component supports Input and Input.Wrapper component features and all input element props. The Cascader documentation does not include all features supported by the component – see the Input documentation to learn about all available features.
Input description
Read only
Set readOnly to prevent opening the dropdown and changing the value:
Disabled
Set disabled to disable the input:
Error state
Pick a valid location
Success state
Looks good!
Loading state
Set the loading prop to display a loader in the right section instead of the chevron:
Accessibility
Set the label prop or aria-label to make the input accessible for screen readers: