For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/components/select.md.
v0.0.57
  • English
  • Select

    Data Entry@rockshin/tao-ui

    Choose 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.

    TSX

    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.

    TSX

    Variants

    Choose outlined, filled, or borderless for the surrounding surface. TaoProvider can set the shared variant.

    TSX

    Disabled controls and options

    An option-level disabled affects one choice. The control-level prop disables all interaction while keeping the current value visible.

    TSX

    Validation states

    Use error or warning with an explanation. Error status also sets aria-invalid on the control.

    Production changes need a review.

    TSX

    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.

    Value: react
    TSX

    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.

    Selected: design, engineering
    TSX

    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.

    1 / 2 selected
    TSX

    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.

    Labels: design
    TSX

    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.

    Labels: (none)
    TSX

    Tag count and length

    maxTagCount controls visible tags, maxTagTextLength shortens labels, and maxTagPlaceholder customizes the overflow message. The selected values stay intact.

    TSX

    Hide selected options

    hideSelected removes selected entries from the suggestions. Removing a tag makes its option available again. This example uses the desktop popup.

    TSX

    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.

    No action yet
    TSX

    Search and data

    Custom filtering

    Use filterOption to match labels, values, and descriptions. Search by city, airport code, or country, such as hnd or Japan.

    TSX

    Grouped options

    Nest options to form groups. Searching keeps the matching entries under their group labels; group labels are not selectable values.

    TSX

    Dependent selections

    When the upstream selection changes, update both the dependent options and value. Here the region determines the available cities.

    Asia / Tokyo
    TSX

    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.

    TSX

    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.

    TSX

    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.

    TSX

    Custom option rendering

    optionRender receives the option and its flattened index. Compose labels and supporting details while Select keeps the keyboard and selection behavior.

    TSX

    Custom selected label

    labelRender customizes the selected single-value label independently of the option list. Here it adds the airport code beside the city.

    TSX

    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.

    TSX

    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.

    TSX

    Semantic styles

    Customize public semantic parts through styles and classNames without private selectors. The popup receives them even when rendered through a portal.

    TSX

    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.

    TSX

    placement sets the preferred side and alignment. The popup still avoids viewport collisions. This example uses desktop popups.

    TSX

    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.

    TSX

    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.

    TSX

    Controlled open and focus

    Control popup visibility with open and onOpenChange. Use the ref methods focus() and blur() to coordinate external actions.

    Popup: closed
    TSX

    getPopupContainer chooses the popup DOM container. Leave room for it and avoid ancestor clipping. This example mounts the popup inside its local panel.

    TSX

    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.

    TSX

    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.

    Not submitted
    TSX

    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.

    390 × 640
    TSX

    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 onChange argument contains matching existing options. A newly created tag may not have a matching option object.
    • The tag overflow example uses a numeric maxTagCount to 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

    PropertyDescriptionTypeDefault Value
    optionsAvailable options; nested options form groups.SelectOption[] (Required)-
    valueControlled selection. Use an array for multiple or tags mode.string | string[] | undefined-
    defaultValueInitial selection for an uncontrolled Select.string | string[] | undefined-
    onChangeCalled with the new selection and its matching option or options.((value: string | string[], option?: SelectOption | SelectOption[] | undefined) => void) | undefined-
    onSelectCalled when an option is selected.((value: string, option: SelectOption) => void) | undefined-
    onDeselectCalled when a selected option is removed.((value: string, option: SelectOption) => void) | undefined-
    onClearCalled when the selection is cleared.(() => void) | undefined-
    modeMultiple selection or free-form tags. Omit for single selection."multiple" | "tags" | undefined-
    placeholderHint displayed when no value is selected.string | undefined-
    sizeControl and desktop popup size; inherits from TaoProvider when omitted.TaoSize | undefined-
    variantControl appearance; inherits from TaoProvider when omitted.TaoVariant | undefined-
    disabledDisable interaction; inherits from TaoProvider when omitted.boolean | undefined-
    statusValidation appearance: error or warning.TaoStatus | undefined-
    showSearchEnable searching the option list.boolean | undefined-
    filterOptionCustom search predicate receiving the query and option.((input: string, option: SelectOption) => boolean) | undefined-
    searchValueControlled search input text.string | undefined-
    onSearchCalled when the search text changes.((value: string) => void) | undefined-
    allowClearShow a clear action, optionally with a custom icon.boolean | { clearIcon?: ReactNode; } | undefined-
    loadingShow the loading indicator.boolean | undefined-
    loadingIconReplace the default loading indicator.ReactNode-
    notFoundContentContent shown when there are no matching options. Defaults to No results.ReactNode-
    prefixContent before the selected value.ReactNode-
    suffixIconReplace the dropdown indicator.ReactNode-
    removeIconReplace the remove icon on selected tags.ReactNode-
    autoFocusFocus the control when it mounts.boolean | undefined-
    idIdentifier for the control and its associated label.string | undefined-
    nameName used for form submission.string | undefined-
    openControlled popup visibility.boolean | undefined-
    defaultOpenInitial popup visibility.boolean | undefined-
    onOpenChangeCalled when popup visibility changes.((open: boolean) => void) | undefined-
    placementDesktop popup position. Defaults to bottomLeft.SelectPlacement | undefined-
    popupMatchSelectWidthDesktop popup width: match the trigger, use intrinsic width, or specify pixels. Defaults to true.number | boolean | undefined-
    listHeightDesktop option-list height in pixels. Defaults to 256.number | undefined-
    getPopupContainerChoose the desktop popup portal container; mobile drawers portal to document.body.((trigger: HTMLElement) => HTMLElement) | undefined-
    optionRenderCustomize each option's content.((option: SelectOption, info: { index: number; }) => ReactNode) | undefined-
    optionLabelWrapWrap built-in option labels without truncation on desktop and mobile. Defaults to false; custom optionRender controls its own content.boolean | undefined-
    labelRenderCustomize the selected option's label.((option: SelectOption) => ReactNode) | undefined-
    popupRenderWrap or extend the desktop menu or mobile drawer content.((menu: ReactNode) => ReactNode) | undefined-
    tagRenderCustomize a selected tag, including its remove action.((props: TagRenderProps) => ReactNode) | undefined-
    maxTagCountMaximum visible tags, or fit tags to the available width with 'responsive'.number | "responsive" | undefined-
    maxTagPlaceholderContent representing selected tags hidden by maxTagCount.ReactNode | ((omittedValues: SelectOption[]) => ReactNode)-
    maxTagTextLengthMaximum displayed character count for each tag label.number | undefined-
    maxCountMaximum number of selected values in multiple or tags mode.number | undefined-
    autoClearSearchValueClear the search after selecting an option. Defaults to true.boolean | undefined-
    tokenSeparatorsCharacters that split entered text into selections in multiple or tags mode.string[] | undefined-
    hideSelectedHide already selected options from the list.boolean | undefined-
    mobileForce mobile or desktop. Otherwise use viewport <576px; an open popup keeps its presentation until closed.boolean | undefined-
    mobileTitleMobile drawer title. Defaults to the Form.Item/FormField label, then locale text.ReactNode-
    classNameCSS class on the root element.string | undefined-
    styleInline styles on the root element.CSSProperties | undefined-
    classNamesCSS classes keyed by typed semantic parts.Partial<Record<SelectSemanticPart, string>> | undefined-
    stylesInline styles keyed by typed semantic parts.Partial<Record<SelectSemanticPart, CSSProperties>> | undefined-

    SelectOption

    PropertyTypeDescription
    labelReactNodeOption text; prefer a string for default filtering and trigger display.
    valuestringUnique value; groups also need a stable value.
    disabledbooleanPrevent selecting or removing this option.
    iconReactNodeOption icon.
    descriptionReactNodeSupporting text.
    optionsSelectOption[]Nested options; makes the entry a group.

    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.