Select
@rockshin/tao-uiChoose one or more values, search options, create tags, and customize their presentation. The examples below cover the currently supported capabilities and can each be copied and run independently.
Examples normally adapt to a mobile drawer. Those described as desktop examples explicitly set mobile={false} to demonstrate input, menu, or popup-specific behavior.
Basics and appearance
Basic usage
Define choices with options and an initial selection with defaultValue. FormField gives the control an accessible label.
Three sizes
Use small, medium, and large for compact toolbars, standard forms, and prominent controls. Desktop option text and row height follow the control size; mobile drawers retain touch-friendly list sizing.
Variants
Choose outlined, filled, or borderless for the surrounding surface. TaoProvider can set the shared variant.
Disabled controls and options
An option-level disabled affects one choice. The control-level prop disables all interaction while keeping the current value visible.
Validation states
Use error or warning with an explanation. Error status also sets aria-invalid on the control.
Choose an environment before continuing.
Production changes need a review.
Controlled selection
Keep external state in sync with value and onChange. Clearing a single selection emits an empty string; an external action can also update the value.
Multiple selection and tags
Multiple selection
mode="multiple" uses an array of strings. Remove a tag or select an option again to deselect it; allowClear clears the entire selection.
Maximum selection count
maxCount limits the number of selections. At the limit, unselected options are disabled until an item is removed. This example uses the desktop popup.
Tags
Combine mode="tags" with showSearch to create new values with Enter. notFoundContent={null} hides an empty suggestion popup. This example uses the desktop input.
Token separators
Paste design,frontend;docs and press Enter to split and deduplicate values. In multiple mode, tokens must match existing values or labels; tags can create new values.
Paste design,frontend;docs, then press Enter.
Tag count and length
maxTagCount controls visible tags, maxTagTextLength shortens labels, and maxTagPlaceholder customizes the overflow message. The selected values stay intact.
Hide selected options
hideSelected removes selected entries from the suggestions. Removing a tag makes its option available again. This example uses the desktop popup.
Selection and clear events
onChange provides the full value and matching existing options. onSelect, onDeselect, and onClear describe individual actions. Newly created tags have no existing option object.
Search and data
Search and clear
showSearch matches option labels without case sensitivity. Try sv, select a result, then clear it to choose again.
Custom filtering
Use filterOption to match labels, values, and descriptions. Search by city, airport code, or country, such as hnd or Japan.
Controlled search
Manage the query with searchValue and onSearch; the caller decides when to clear it. Uncontrolled multi-select can retain it with autoClearSearchValue={false}. This example uses desktop input.
Grouped options
Nest options to form groups. Searching keeps the matching entries under their group labels; group labels are not selectable values.
Dependent selections
When the upstream selection changes, update both the dependent options and value. Here the region determines the available cities.
Async search and loading
This example simulates a search request with local data and a 500ms delay. It cancels stale work and combines loading, controlled search, and an empty state. Replace the local lookup with your API in an application. It uses desktop input.
Local demo with a simulated 500ms request.
Custom empty state
notFoundContent accepts text or a React node for an empty list or no matching results. An external action can populate the options.
Content and styles
Option icons and descriptions
Add context with option-level icon and description. Keep label short and textual for searching and the selected value.
Custom option rendering
optionRender receives the option and its flattened index. Compose labels and supporting details while Select keeps the keyboard and selection behavior.
Custom selected label
labelRender customizes the selected single-value label independently of the option list. Here it adds the airport code beside the city.
Custom tag rendering
Customize multi-select tags with tagRender. Preserve removal behavior using the supplied closable, disabled, and onClose. This example reuses tao-ui Tag.
Prefix, suffix, and action icons
Use prefix, suffixIcon, allowClear.clearIcon, removeIcon, and loadingIcon for the corresponding slots. Custom icons retain the built-in clear and remove behavior.
Semantic styles
Customize public semantic parts through styles and classNames without private selectors. The popup receives them even when rendered through a portal.
Popup and interaction
Extend the popup
Keep the original menu and add actions through popupRender. Here a footer creates a project by name; the Add button preserves input focus. This example uses the desktop popup.
Popup placement
placement sets the preferred side and alignment. The popup still avoids viewport collisions. This example uses desktop popups.
Popup width and list height
popupMatchSelectWidth matches the trigger by default, or accepts false or a pixel width. Numeric widths currently retain the trigger's minimum width; this example pairs a 200px control with a 240px popup. listHeight limits the scrollable option area. This is a regular list, not a virtualized list.
Long filenames
Enable optionLabelWrap to show built-in option labels in full, including filenames without spaces. Labels wrap without a line limit, and the checkmark keeps its own column aligned with the first line. Desktop popup widths stay within the available viewport; use popupMatchSelectWidth for a wider menu. Mobile drawers also wrap. Selected tags stay compact; custom optionRender content controls its own wrapping.
Controlled open and focus
Control popup visibility with open and onOpenChange. Use the ref methods focus() and blur() to coordinate external actions.
Popup container
getPopupContainer chooses the popup DOM container. Leave room for it and avoid ancestor clipping. This example mounts the popup inside its local panel.
Forms and mobile
Provider defaults
Use TaoProvider to share size, variant, and disabled. Local props take precedence; the second control overrides the inherited size and disabled state.
Form submission
Desktop single-select can use name with native FormData; id associates the field label. Serialize controlled values explicitly for multiple selection and mobile drawers. This demo displays the result without sending a request.
Mobile drawer titles use mobileTitle, then the nearest Form.Item / FormField label, then localized default text. Required marks and help text are excluded; placeholders only describe the input. For standalone controls or native HTML labels, pass mobileTitle="Departure date" explicitly.
Mobile single and multiple selection
Select follows the viewport by default; mobile forces the bottom drawer. Single selection commits immediately. Multiple selection commits with Done; closing discards the draft. Try the mobile interaction on desktop here.
Usage notes
- For a few mutually exclusive choices that should be compared directly, prefer Radio.
- Single selection uses a string; multiple selection and tags use arrays. The second
onChangeargument contains matching existing options. A newly created tag may not have a matching option object. - The tag overflow example uses a numeric
maxTagCountto demonstrate a fixed number of visible tags. - Mobile drawers support search, groups, custom options, and single/multiple confirmation. Examples marked as desktop use
mobile={false}to demonstrate input and popup interactions. Placement, popup width, and portal containers configure desktop popups. - Desktop single-select supports native form submission through
name. Serialize controlled values in application submission logic for mobile and multiple selection.
API
Select
SelectOption
TagRenderProps
tagRender receives { label, value, closable, disabled, onClose }. Use closable to decide whether to offer removal, and call onClose to perform it.
SelectRef
The ref exposes focus(), blur(), and nativeElement. Avoid depending on private DOM structure.