Select (Native)

TuiSelectNative is a component encapsulated based on the browser's native HTML <select> element. Compared to the feature-rich TuiSelect, it is more lightweight, and its interactions strictly follow the native behavior of the operating system or browser. It is primarily used in scenarios where UI customization requirements are low or where native controls are specifically needed.

Basic Usage

Configuration-based Rendering

Pass an array of options through the options property. By default, it recognizes the label and value fields, but these can be customized using labelKey and valueKey.

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

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

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

Slot-based Rendering

Construct the component using the <TuiOptionNative> sub-component.

<template>
  <TuiSelectNative v-model="value">
    <TuiOptionNative label="Option A" value="A" />
    <TuiOptionNative label="Option B" value="B" />
  </TuiSelectNative>
</template>

Multiple Selection

Set the multiple attribute to enable multiple selection mode.

Note

The behavior of the native <select multiple> is typically an expanded List Box where users need to hold the Ctrl (Windows) or Command (Mac) key to perform multiple selections. This is completely different from the Tag-based display used by TuiSelect.

<template>
  <TuiSelectNative multiple v-model="selectedValues" :options="options" />
</template>

Decoration and Status

Clearable

Although the native Select does not support a clear button, the component implements this feature through an outer wrapper. When clearable is set, a delete icon is displayed on hover (only valid in single-selection mode).

<TuiSelectNative v-model="val" clearable :options="options" />

Icon

Icons can be added to the head of the selection box using the icon property.

<TuiSelectNative icon="tui-icon ti-star" v-model="val" :options="options" />

Size

Supports large, small, and default sizes.

<TuiSelectNative size="small" v-model="val1" :options="options" />
<TuiSelectNative size="large" v-model="val2" :options="options" />

API Reference

TuiSelectNative Props

Property	Type	Default	Description
modelValue	String/Number/Array	-	Bound value.
options	Array	[]	Data source.
valueKey	String	'value'	The key name for the value in the option object.
labelKey	String	'label'	The key name for the label in the option object.
disabledKey	String	'disabled'	The key name for the disabled state in the option object.
multiple	Boolean	false	Whether to enable multiple selection (native behavior).
disabled	Boolean	false	Whether it is disabled.
clearable	Boolean	false	Whether to show the clear button.
size	String	null	Size. Options: large, small.
icon	String	-	Header icon class name.
placeholder	String	-	Placeholder (usually displayed as the first disabled option).
width	String/Number	-	Width.
required	Boolean	false	Native required attribute.
autofocus	Boolean	false	Native autofocus attribute.
name	String	-	Native name attribute.
id	String	-	Native id attribute.
customClass	String	-	Custom class name.

TuiSelectNative Emits

Event Name	Description	Callback Parameters
update:modelValue	Triggered when the bound value changes.	(value)
change	Triggered when the option changes.	(value)
focus	Triggered when gaining focus.	(event)
blur	Triggered when losing focus.	(event)
clear	Triggered when the clear button is clicked.	-

TuiSelectNative Methods (Expose)

Method Name	Description
focus	Makes the selection box gain focus.
blur	Makes the selection box lose focus.
getSelectElement	Gets the internal native select DOM element.
syncSelectedState	Manually syncs the selected state.

TuiOptionNative Props

Property	Type	Default	Description
value	String/Number/Boolean	Required	The value of the option.
label	String/Number	-	The label of the option.
disabled	Boolean	false	Whether it is disabled.
selected	Boolean	false	Whether it is selected.
customClass	String	-	Custom class name.