Dropdown Selector

TuiSelect is used to display and select content from a dropdown menu when there are many options available. It supports single selection, multiple selection, search filtering, and flexible option rendering methods (configuration-based or slot-based).

Basic Usage

Configuration-based Rendering (Options Prop)

The most basic usage is to pass data through the options property. This is suitable for scenarios with simple data structures where custom option styling is not required. The options array items must contain label and value fields.

<script setup>
import { ref } from 'vue';

const value = ref('A');
const options = [
  { value: 'A', label: 'Option A' },
  { value: 'B', label: 'Option B' },
  { value: 'C', label: 'Option C', disabled: true }
];
</script>

<template>
  <TuiSelect v-model="value" :options="options" placeholder="Please select" />
</template>

Slot-based Rendering (Slot Mode)

Using the <TuiOption> sub-component provides more flexibility in rendering options. This method allows you to embed icons, images, or complex HTML structures within the options.

<template>
  <TuiSelect v-model="value" placeholder="Select">
    <TuiOption 
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
      :disabled="item.disabled"
    />
  </TuiSelect>
</template>

Multiple Selection

Set the multiple property to enable multiple selection mode. In this mode, the v-model bound value is an array.

Basic Multiple Selection

<TuiSelect multiple v-model="selectedList" :options="options" />

Collapsing Tags (Collapse Tags)

When too many items are selected, you can use the following properties to control the display effect and prevent the input box height from expanding infinitely:

• collapseTags: Whether to collapse multiple selection tags (default is true).
• maxCollapseTags: The threshold of tags after which collapsing begins (default is 2).

<template>
  <TuiSelect 
    multiple 
    :maxCollapseTags="1" 
    v-model="vals" 
    :options="options" 
  />
  
  <TuiSelect 
    multiple 
    :collapseTags="false" 
    v-model="vals" 
    :options="options" 
  />
</template>

Multiple Selection Limit

Use the multipleLimit property to restrict the maximum number of items a user can select.

<TuiSelect multiple :multipleLimit="3" placeholder="Select up to 3 items" ... />

Filtering and Search

Set filterable to true to enable the search function.

Default Filtering

By default, the component matches options where the label contains the input keyword (case-insensitive).

<TuiSelect filterable v-model="value" :options="options" />

Custom Filtering (Filter Method)

Use filterMethod to customize the search logic (e.g., case-sensitive matching or matching both value and label).

<script setup>
const myFilter = (option, query) => {
  // Example: Match only by value and use case-sensitivity
  return option.value.includes(query);
};
</script>

<template>
  <TuiSelect 
    multiple 
    filterable 
    filterPlaceholder="Enter Value to search"
    :filterMethod="myFilter" 
    v-model="value" 
    :options="options" 
  />
</template>

Status and Appearance

• Clearable: When clearable is enabled, a clear button appears on hover.
• Disabled: Disables the entire selector.
• Size: Supports large, default, and small.
• Icon: Add a custom icon to the end of the input box via the icon property.
• FitInputWidth: Default is true, meaning the dropdown menu width matches the input box. When set to false, the menu width adjusts based on content (useful for very long option text).

<template>
  <div class="demo-gap">
    <TuiSelect size="small" placeholder="Small" ... />
    <TuiSelect size="large" placeholder="Large" ... />
    
    <TuiSelect :fitInputWidth="false" placeholder="Wide option adaptation" ... />
  </div>
</template>

API Reference

TuiSelect Props

Property	Type	Default	Description
modelValue	String/Number/Array	-	Bound value. Primitive type for single select, array for multiple select.
options	Array	[]	Option data source, used only for configuration-based rendering.
multiple	Boolean	false	Whether multiple selection is enabled.
disabled	Boolean	false	Whether the component is disabled.
clearable	Boolean	false	Whether options can be cleared.
filterable	Boolean	false	Whether the selector is searchable.
filterMethod	Function	-	Custom search method (option, query) => boolean.
filterPlaceholder	String	-	Placeholder for the search box.
collapseTags	Boolean	true	Whether to display selected values as text in multiple selection mode.
maxCollapseTags	Number	2	Max number of tags shown before collapsing in multiple selection.
multipleLimit	Number	-	Max number of items a user can select; 0 means no limit.
size	String	'default'	Dimensions. Options: large, default, small.
placeholder	String	-	Placeholder text.
icon	String	-	Custom suffix icon class name.
fitInputWidth	Boolean	true	Whether the dropdown popup width matches the input box.
offset	Number	10	Vertical offset of the dropdown popup.
allowCreate	Boolean	false	Whether to allow users to create new entries (requires filterable).

TuiSelect Emits

Event Name	Description	Callback Parameters
update:modelValue	Triggered when the bound value changes.	(value)
change	Triggered when the selected value changes.	(value)
visible-change	Triggered when the dropdown appears or hides.	(visible: Boolean)
clear	Triggered when the clear button is clicked.	-
blur	Triggered when the input box loses focus.	(event)
focus	Triggered when the input box gains focus.	(event)

TuiOption Props

Property	Type	Default	Description
value	String/Number/Object	-	The value of the option.
label	String	-	The label of the option; defaults to value if not set.
disabled	Boolean	false	Whether the option is disabled.

Global Interaction Monitoring

The TuiSelect component is deeply integrated with TechUI's global service (TuiService). It implements intelligent closing interactions by listening to global signals to ensure the dropdown menu only shows when needed:

• ESC Response (escCounter): The component monitors global ESC key triggers in real-time. When the Esc key is pressed, escCounter updates, and any expanded dropdown menu will automatically retract.
• Intelligent Click Detection (clickCounter): The component listens for global click events. Each time a click occurs, the global service updates clickCounter and provides the clickTarget. The component performs a precise "Contains Check": it only triggers the hide logic if the click target is not inside the Select component itself (including both the input box and the dropdown panel). This ensures accurate "Click Outside" functionality in complex layouts.

Positioning Core

The underlying positioning of the TuiSelect dropdown panel relies entirely on the Floating UI library.

This means the component handles dropdown display at screen edges automatically:

• Smart Flipping (Flip): If there is insufficient space below, the menu flips to display above the input box.
• Viewport Correction (Shift): Ensures the menu remains within the visible viewport and is not truncated.
• Follow Scroll: The menu dynamically updates its position during page scrolling to maintain its relative anchor to the input box.

Developers can focus on business logic while the underlying engine manages complex geometric calculations.