Usage
TreeSelect allows picking one or more values from hierarchical data:
TreeSelect with uncontrolled forms
Set name to submit node values rather than labels. In multiple and checkbox modes, values share one field; hiddenInputValuesDivider sets the separator:
Virtualized dropdown
Use virtualizer to render only the visible tree rows. Expand or collapse a category to change which products appear:
Data prop
Data passed to the data prop must follow the same rules as the Tree component:
- Data must be an array of
TreeNodeDataobjects - Each node must have
valueandlabelkeys,valuemust be unique - Each node can have a
childrenkey with an array of child nodes
Selection modes
Use the mode prop to change the selection mode:
single(default) – single value selection, renders as an inputmultiple– multiple value selection, renders as pillscheckbox– checkbox selection with parent-child cascade, renders as pills
Multiple mode
Checkbox mode
In checkbox mode, checking or unchecking a parent node does the same for all its children. If only some children are checked, the parent is displayed in indeterminate state:
Controlled
Searchable
Set searchable prop to allow filtering options by user input.
Matching nodes are displayed together with their ancestors:
Nothing found
Set nothingFoundMessage prop to display a message when no options match the search query
or there is no data:
Clearable
Set the clearable prop to display the clear button in the right section:
Expand on click
Set expandOnClick prop to expand and collapse a parent node when it is clicked, not only with the chevron.
In checkbox mode, the click also toggles the checked state:
Connecting lines
TreeSelect renders connecting lines between parent and child nodes by default.
Set withLines={false} to disable them:
Check strictly
Set checkStrictly to disable parent-child cascade in checkbox mode, each node is checked independently:
Checked strategy
checkedStrategy prop controls which checked nodes appear in the value and pills in checkbox mode:
child(default) – only leaf nodes appear in the valueall– all checked nodes (parents and children) appear in the valueparent– only the topmost fully-checked parents appear in the value
Max values
Set maxValues prop to limit the number of selected values in multiple and checkbox modes:
renderNode
Use renderNode callback to customize node rendering in the dropdown:
The payload includes an expand function that toggles the node. Use it to build a custom
expand control, set expandOnClick={false} to expand nodes only with your control:
renderPill
Use renderPill callback to customize pills of selected values in multiple and
checkbox modes. Call onRemove from your pill to remove the value.
The overflow pill is customized with maxDisplayedValuesContent instead:
Scrollable dropdown
The options list is wrapped with ScrollArea.Autosize, set maxDropdownHeight prop
to change the dropdown max-height:
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 TreeSelect, for example withinPortal:
Change dropdown z-index
Control dropdown opened state
Use dropdownOpened prop to control the dropdown opened state, onDropdownOpen and onDropdownClose
to listen to its changes:
Dropdown position
By default, the dropdown is displayed below the input if there is enough space, otherwise above it.
Set position and middlewares props to change this behavior, they are passed down to
the underlying Popover. Example of a dropdown that is always displayed above the input:
Dropdown width
By default, the dropdown width is equal to the input width. Set width in comboboxProps to change it:
Dropdown offset
Set offset in comboboxProps to change the dropdown offset:
Dropdown animation
By default, dropdown animations are disabled. Set transitionProps to enable them,
they are passed down to the underlying Transition component:
Dropdown padding
Dropdown shadow
Keyboard navigation
TreeSelect supports the following keyboard interactions when the dropdown is open:
ArrowRight– expand the highlighted parent nodeArrowLeft– collapse the highlighted parent node, or move to its parentArrowUp/ArrowDown– move between optionsEnter– select the highlighted option
Expand state
Use defaultExpandedValues, defaultExpandAll or expandedValues with onExpandedChange to manage expanded nodes:
Left and right sections
TreeSelect 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
TreeSelect component supports Input and Input.Wrapper component features and all input element props. The TreeSelect 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 make the input read only, the dropdown is not displayed and onChange is not called:
Disabled
Set disabled to disable the input:
Error state
Invalid value
Success state
Looks good!
Get element ref
Accessibility
If TreeSelect is used without the label prop, it will not be announced properly by screen readers:
Set aria-label to make the input accessible. In this case the label will not be visible, but screen readers will announce it:
If the label prop is set, the input will be accessible and it is not required to set aria-label:
When clearable is set, use clearButtonProps to set aria-label on the clear button: