Coral is a thoroughly developed design system widely adopted by developers and designers for creating beautiful and user-friendly Sea internal products.
Copyright © 2018-2025 Sea Labs
Blogs
All blogsTreeSelect
Designer doc
TreeSelect is an input component to select a value from an tree-structure option list.
Example
Basic Usage
View code
An icon button can be used to trigger dropdown selection too.
View code
Rendering from data
Different from Ant Design’s TreeSelect, Coral’s doesn’t include tree rendering from data inside the component, rather a utility function renderFromData is provided.
View code
Client-side search
In case you want to search locally within a tree, instead of using TreeSelectNode or renderFromData, you can use TreeSelectSearchableNodes inside TreeSelectList.
This component handles nodes pruning and expandedValues based on searchValue and the data you provided (same schema as utility function renderFromData). You only need to pass data prop and filter function.
View code
Note that searching in TreeSelect is a really complicated thing - ease of usage has some tradeoffs with flexibility, and TreeSelectSearchableNodes chooses for the former. While TreeSelectSearchableNodes component should never introduce any breaking changes, another new search component may be created if this component cannot cover all use cases.
Managing client-side search
By default, TreeSelectSearchableNodes will set expandedValues state to display all matched search nodes on every searchValue changes.
To customize a little bit how the expand state behaves, you can pass:
- resetExpandedTo: array of values. This is different from expandedValues and initialExpandedValues in TreeSelect because this is triggered on query changes.
- skip: either boolean or function accepting query. If the result is true, it includes all nodes and will set expandedValues to resetExpandedTo.
That said, the default value of resetExpandTo is [] (empty array), and skip is query => !query.length.
Below is an example of “Search only if query has more than 3 characters”.
View code
More Examples
View code
Accessibility
- Right arrow:
- When focus is on a closed node, opens the node; focus and selection do not move.
- When focus is on a open node, moves focus to the first child node and selects it if it is selectable.
- When focus is on an end node, does nothing.
- Left arrow:
- When focus is on an open node, closes the node.
- When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node and selects it if it is selectable.
- When focus is on a root node that is also either an end node or a closed node, does nothing.
Relevant components
References
- WAI-ARIA: Keyboard Interactions and Roles, States, and Properties
- Ant Design: Tree and TreeSelect
- Material-UI: TreeView
API
TreeSelect
| Prop name | Type | Default | Description |
|---|---|---|---|
| expandedValues | SelectValue[] | ||
| id | string | ||
| initialExpandedValues | SelectValue[] | [] | |
| initialIsOpen | boolean | ||
| initialKeyboardHighlightedIndex | number | ||
| initialMouseHighlightedIndex | number | ||
| initialSearchValue | string | ||
| initialSelectedIndex | number | ||
| initialValue | SelectValue | ||
| isOpen | boolean | ||
| keyboardHighlightedIndex | number | ||
| mouseHighlightedIndex | number | ||
| onChange | ChangeCallback | Called when selected value is changed. Different from onSelect, onChange is not called when the value is already selected. | |
| onExpandedValuesChange | (expanded: SelectValue[]) => void | ||
| onIsOpenChange | (isOpen: boolean) => void | ||
| onKeyboardHighlightedIndexChange | (index: number) => void | ||
| onMouseHighlightedIndexChange | (index: number) => void | ||
| onSearch | SearchCallback | ||
| onSelect | ChangeCallback | Different from onChange: onSelect is triggered even if the option's value is the selected one. | |
| onSelectedIndexChange | (index: number) => void | ||
| searchValue | string | This is not the selected value. Rather, it's a search value on input if you use SelectSearch. | |
| selectedIndex | number | ||
| stateReducer | AcdcStateReducer | (state, { nextState }) => nextState | |
| value | SelectValue |
TreeSelectButton
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| disabled | boolean | Equivalent to button's disabled property. | |
| keyboardClickKeys | string[] | ||
| onBlur | FocusEventHandler<HTMLDivElement> | ||
| onClick | MouseEventHandler<HTMLDivElement> | ||
| onKeyDown | KeyboardEventHandler<HTMLDivElement> | ||
| onKeyUp | KeyboardEventHandler<HTMLDivElement> | ||
| onMouseDown | MouseEventHandler<HTMLDivElement> | ||
| onMouseLeave | MouseEventHandler<HTMLDivElement> | ||
| onMouseUp | MouseEventHandler<HTMLDivElement> | ||
| onRelease | EventHandler<SyntheticEvent<HTMLDivElement, Event>> | Callback that's triggered after click i.e. mouseup and keyup of enter or space. | |
| onTouchEnd | TouchEventHandler<HTMLDivElement> | ||
| onTouchStart | TouchEventHandler<HTMLDivElement> | ||
| placeholder | ReactNode | ||
| rightElement | ReactNode |
TreeSelectHighlighter
| Prop name | Type | Default | Description |
|---|---|---|---|
| text | string |
TreeSelectIconButton
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| badgeProps | Omit<BadgeProps, "children"> | ||
| colorType | ColorTypes | Set color based on theme. If color is specified, that prop is used instead of this. | |
| disabled | boolean | Equivalent to button's disabled property. | |
| keyboardClickKeys | string[] | ||
| loading | boolean | ||
| onBlur | FocusEventHandler<HTMLDivElement> | ||
| onClick | MouseEventHandler<HTMLDivElement> | ||
| onKeyDown | KeyboardEventHandler<HTMLDivElement> | ||
| onKeyUp | KeyboardEventHandler<HTMLDivElement> | ||
| onMouseDown | MouseEventHandler<HTMLDivElement> | ||
| onMouseLeave | MouseEventHandler<HTMLDivElement> | ||
| onMouseUp | MouseEventHandler<HTMLDivElement> | ||
| onRelease | EventHandler<SyntheticEvent<HTMLDivElement, Event>> | Callback that's triggered after click i.e. mouseup and keyup of enter or space. | |
| onTouchEnd | TouchEventHandler<HTMLDivElement> | ||
| onTouchStart | TouchEventHandler<HTMLDivElement> | ||
| radius | string | ||
| showBadge | boolean | ||
| size | IconButtonSizes | ||
| tooltip | ReactNode | ||
| tooltipProps | Omit<TooltipProps, "title" | "children"> | ||
| variant | IconButtonVariants |
TreeSelectList
| Prop name | Type | Default | Description |
|---|---|---|---|
| acdcScrollerPropsOptions | UseAcdcScrollerPropsOptions | Options for the useAcdcScrollerProps hook | |
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| container | HTMLElement | ||
| containerProps | DivProps | ||
| elevationLevel | number | ||
| emptyPlaceholder | ReactNode | ||
| footer | ReactNode | ||
| header | ReactElement<any, any> | ||
| immediate | boolean | ||
| lined | boolean | ||
| placement | "left" | "right" | "bottom" | "top" | "top-start" | "top-end" | "left-start" | "left-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | ||
| popperReference | HTMLElement | ||
| popperUpdateKey | string | ||
| width | SelectListWidth |
TreeSelectListFooter
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. |
TreeSelectListSearch
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| autoComplete | "on" | "off" | "nope" | ||
| disabled | boolean | ||
| fullWidth | boolean | width: 100% is too troublesome to handle with custom css because of the nesting | |
| invalid | boolean | ||
| leftElement | ReactNode | ||
| leftElementContainerProps | HTMLAttributes<HTMLDivElement> & { ref?: MutableRefObject<HTMLDivElement>; } | ||
| onChange | (e: ChangeEvent<HTMLInputElement>) => void | ||
| onTextChange | (val: string) => void | ||
| placeholder | ReactNode | ||
| readOnly | boolean | ||
| rightElement | ReactNode | ||
| rightElementContainerProps | HTMLAttributes<HTMLDivElement> & { ref?: MutableRefObject<HTMLDivElement>; } | ||
| type | "number" | "text" | "password" | ||
| wrapperProps | WrapperProps |
TreeSelectNode
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| childrenNodesProps | ChildrenNodesProps | ||
| disabled | boolean | ||
| expandButton | ReactNode | <TreeSelectNodeExpand /> | |
| index | number | ||
| label | ReactNode | <>{value}</> | |
| leftElement | ReactNode | ||
| nodeProps | NodeProps | ||
| value | SelectValue |
TreeSelectNodeExpand
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| colorType | ColorTypes | Set color based on theme. If color is specified, that prop is used instead of this. | |
| disabled | boolean | Equivalent to button's disabled property. | |
| keyboardClickKeys | string[] | ||
| loading | boolean | ||
| onBlur | FocusEventHandler<HTMLDivElement> | ||
| onClick | MouseEventHandler<HTMLDivElement> | ||
| onKeyDown | KeyboardEventHandler<HTMLDivElement> | ||
| onKeyUp | KeyboardEventHandler<HTMLDivElement> | ||
| onMouseDown | MouseEventHandler<HTMLDivElement> | ||
| onMouseLeave | MouseEventHandler<HTMLDivElement> | ||
| onMouseUp | MouseEventHandler<HTMLDivElement> | ||
| onRelease | EventHandler<SyntheticEvent<HTMLDivElement, Event>> | Callback that's triggered after click i.e. mouseup and keyup of enter or space. | |
| onTouchEnd | TouchEventHandler<HTMLDivElement> | ||
| onTouchStart | TouchEventHandler<HTMLDivElement> | ||
| radius | string | ||
| size | IconButtonSizes | ||
| tooltip | ReactNode | ||
| tooltipProps | Omit<TooltipProps, "title" | "children"> | ||
| variant | IconButtonVariants |
TreeSelectSearch
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| autoComplete | "on" | "off" | "nope" | ||
| contentProps | SelectSelectedContentProps | ||
| disabled | boolean | ||
| fullWidth | boolean | width: 100% is too troublesome to handle with custom css because of the nesting | |
| invalid | boolean | ||
| leftElement | ReactNode | ||
| leftElementContainerProps | HTMLAttributes<HTMLDivElement> & { ref?: MutableRefObject<HTMLDivElement>; } | ||
| onChange | (e: ChangeEvent<HTMLInputElement>) => void | ||
| onTextChange | (val: string) => void | ||
| placeholder | ReactNode | ||
| readOnly | boolean | ||
| rightElement | ReactNode | ||
| rightElementContainerProps | HTMLAttributes<HTMLDivElement> & { ref?: MutableRefObject<HTMLDivElement>; } | ||
| type | "number" | "text" | "password" | ||
| wrapperProps | WrapperProps |
TreeSelectSearchableNodes
| Prop name | Type | Default | Description |
|---|---|---|---|
| data | TreeData | ||
| filter | (node: TreeNode, query: string) => boolean | Different from FilterNode in utils. | |
| renderFromData | (data: TreeData) => ReactNode | ||
| resetExpandedTo | SelectValue[] | [] | |
| skip | boolean | ((query: string) => boolean) |