element-plus/docs/en-US/component/select-v2.md

title	lang
Virtualized Select	en-US

Select V2 virtualized selector

:::tip

This component is still under testing, if you found any bug or issue please report it at GitHub for us to fix.

:::

Background

In some use-cases, a single selector may end up loading tens of thousands of rows of data. Rendering that much data into the DOM could be a burden to the browser, which can result in performance issues. For a better user and developer experience, we decided to add this component.

Basic usage

The simplest selector

:::demo

select-v2/basic-usage

:::

Multi select

The basic multi-select selector with tags

:::demo

select-v2/multiple

:::

Hide extra tags when the selected items are too many.

You can collapse tags to a text by using collapse-tags attribute. You can check them when mouse hover collapse text by using collapse-tags-tooltip attribute.

:::demo

select-v2/hide-extra-tags

:::

Filterable multi-select

When the options are overwhelmingly too many, you can use filterable option to enable filter feature for finding out the desired option

:::demo

select-v2/filterable

:::

Disabled selector and select options

You can choose to disable selector itself or the option.

:::demo

select-v2/disabled

:::

Option Grouping

We can group option as we wanted, as long as the data satisfies the pattern.

:::demo

select-v2/grouping

:::

Customized option renderer

We can define our own template for rendering the option in the popup.

:::demo

select-v2/customized-option

:::

Clearable selector

We can clear all the selected options at once, also applicable for single select.

:::demo

select-v2/clearable

:::

Create Option

Create and select new items that are not included in select options

By using the allow-create attribute, users can create new items by typing in the input box. Note that for allow-create to work, filterable must be true.

:::tip

It will be better to set :reserve-keyword="false" when use allow-create

:::

:::demo

select-v2/allow-create

:::

Remote search

Enter keywords and search data from server.

:::demo Set the value of filterable and remote with true to enable remote search, and you should pass the remote-method. remote-method is a Function that gets called when the input value changes, and its parameter is the current input value.

select-v2/remote-search

:::

SelectV2 Attributes

Attribute	Description	Type	Accepted Values	Default
model-value / v-model	biding value	string / number / boolean / object	—	—
multiple	is multiple	boolean	—	false
disabled	is disabled	boolean	—	false
value-key	unique identity key name for value, required when value is an object	string	—	value
size	input box size	string	large/default/small	default
clearable	whether select can be cleared	boolean	—	false
clear-icon	custom clear icon	string / Component	—	CircleClose
collapse-tags	whether to collapse tags to a text when multiple selecting	boolean	—	false
collapse-tags-tooltip	whether show all selected tags when mouse hover text of collapse-tags. To use this, collapse-tags must be true	boolean	true / false	false
multiple-limit	maximum number of options user can select when multiple is true. No limit when set to 0	number	—	0
name	the name attribute of select input	string	—	—
effect	Tooltip theme, built-in theme: dark / light	string	string	light
autocomplete	autocomplete of select input	string	—	off
placeholder	the autocomplete attribute of select input	string	—	Please select
filterable	is filterable	boolean	—	false
allow-create	whether creating new items is allowed. To use this, filterable must be true	boolean	—	false
reserve-keyword	whether reserve the keyword after select filtered option.	boolean	—	true
no-data-text	displayed text when there is no options, you can also use slot empty	string	—	No Data
popper-class	custom class name for Select's dropdown	string	—	—
popper-append-to-body(deprecated)	whether to append the popper menu to body. If the positioning of the popper is wrong, you can try to set this prop to false	boolean	-	false
teleported	whether select dropdown is teleported to the body	boolean	true / false	true
persistent	when select dropdown is inactive and persistent is false, select dropdown will be destroyed	boolean	true / false	true
popper-options	Customized popper option see more at popper.js	object	-	-
automatic-dropdown	for non-filterable Select, this prop decides if the option menu pops up when the input is focused	boolean	-	false
height	The height of the dropdown panel, 34px for each item	number	-	170
scrollbar-always-on	Controls whether the scrollbar is always displayed	boolean	-	false
remote	whether search data from server	boolean	—	false
remote-method	function that gets called when the input value changes. Its parameter is the current input value. To use this, filterable must be true	function(keyword: string)	—	—

SelectV2 Events

Event Name	Description	Params
change	triggers when the selected value changes	current selected value
visible-change	triggers when the dropdown appears/disappears	true when it appears, and false otherwise
remove-tag	triggers when a tag is removed in multiple mode	removed tag value
clear	triggers when the clear icon is clicked in a clearable Select	—
blur	triggers when Input blurs	(event: Event)
focus	triggers when Input focuses	(event: Event)

SelectV2 Slots

Name	Description
default	Option renderer
empty	content when options is empty
prefix	prefix content of input