renderOption prop for custom option rendering
Use the renderOption prop to customize how options are rendered in columns. The function receives the option and its column level.
cascader/props
29 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
withCheckIcon and checkIconPosition props
Use the withCheckIcon prop to toggle the check icon on the selected option and checkIconPosition to change its position (left or right).
disabled property on options
Set the disabled property on an option to prevent it from being selected or expanded. Disabled options are skipped during keyboard navigation.
leftSection and rightSection props
Cascader supports leftSection and rightSection props the same way as other inputs. These sections are usually used to add icons.
CascaderOption data structure
Data passed to the data prop is an array of CascaderOption objects. Each option must have a unique value across the whole data tree. The label field is optional; value is used when label is not set. The children field contains an array of nested options. The disabled field prevents an option from being selected or expanded.
Cascader value and onChange callback
Cascader value is an ordered array of option values (a path from root to node) or null when nothing is selected. The onChange callback is called with two parameters: the selected path (string[] | null) and the resolved chain of CascaderOption objects.
Cascader default selection behavior
By default, only leaf options (options without children) can be selected. Clicking a parent option only expands the next column.
changeOnSelect prop allows selecting parent options
Set the changeOnSelect prop to allow selecting any option, not only leaves. When enabled, clicking a parent option both selects its path and expands the next column, so any intermediate level is a valid value.
closeOnSelect prop behavior and defaults
The closeOnSelect prop controls whether the dropdown is closed after a value is selected. When it is not set, it defaults to the opposite of allowDeselect: the dropdown stays open by default (so the selection can be toggled off), unless allowDeselect={false} is set. Set closeOnSelect explicitly to override this behavior.
allowDeselect prop default behavior
By default, clicking the selected option again removes the value. Set allowDeselect={false} to disable this behavior.
expandTrigger prop for hover expand
By default, the next column is opened when an option is clicked. Set expandTrigger="hover" to open the next column on hover instead – selecting a leaf still requires a click.
safeAreaPolygon prop for hover expand behavior
With expandTrigger="hover", the open column stays in place while the cursor moves diagonally toward it – options that the cursor passes over on the way do not replace it. Set safeAreaPolygon={false} to expand on every hover immediately, or pass an object to configure Floating UI safePolygon options.
withColumns prop for flat list layout
Cascading columns require horizontal space and are not ideal for narrow screens. Set withColumns={false} to render options as a flat list of full paths (the same way as search results) instead of columns – this layout works well on mobile.
maxDisplayedLevels prop default value and behavior
The maxDisplayedLevels prop defaults to 3 and limits how many columns are displayed next to each other. When you drill deeper than the limit, the earliest columns are replaced by the deeper ones and a control is displayed on the left. Click it to reveal the previous levels; a control on the right then lets you return to the deeper levels.
searchable prop enables filtering
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.
filter prop for custom search matching
Use the filter prop to customize how paths are matched during search. The filter function receives query (string) and options (CascaderOption[]) parameters and should return a boolean indicating whether the options match.
renderSearchOption prop for custom search result rendering
Use the renderSearchOption prop to customize how search results are rendered. The function receives query (string) and options (CascaderOption[]) parameters.
searchValue and onSearchChange for controlled search
Use searchValue and onSearchChange props to control the search value. searchValue is a string representing the current search input, and onSearchChange is a callback that receives the new search value.
nothingFoundMessage prop for empty search results
Set the nothingFoundMessage prop to display a message when no options match the search query.
separator and formatValue props for display value
By default, the selected path is displayed in the input as option labels joined by the separator (/ by default). Use the separator prop to change the divider and the formatValue prop to fully customize the input label.
columnWidth and maxDropdownHeight props
Use the columnWidth prop to set a fixed width for every column and maxDropdownHeight to control the height of a column before it becomes scrollable (260 by default).
clearable prop and clearSectionMode
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.
scrollAreaProps for column scrolling
Each column is scrollable. Use the maxDropdownHeight prop to control the height of a column before it becomes scrollable and scrollAreaProps to pass props down to the ScrollArea in each column.
Controlling dropdown opened state
Use dropdownOpened, defaultDropdownOpened, onDropdownOpen and onDropdownClose props to control the dropdown opened state.
Dropdown position via comboboxProps
Use comboboxProps to pass props down to the underlying Combobox and Popover. For example, set comboboxProps={{ position: 'top' }} to change the dropdown position.
Cascader inside Popover
To use Cascader inside a Popover, set comboboxProps={{ withinPortal: false }}.
readOnly prop disables dropdown and onChange
Set readOnly to make the input read only. When readOnly is set, Cascader will not open the dropdown and will not call the onChange function.
disabled prop prevents user interaction
Set disabled to disable the input. When disabled is set, the user cannot interact with the input and Cascader will not open the dropdown.
loading prop displays loader
Set the loading prop to display a loader in the right section instead of the chevron.