FaSelectV2

A virtualized selector for large datasets. Supports local and remote data, paginated results, custom options, label synchronization and explicit refresh. Actual option height and virtual scrolling offsets both follow itemHeight.

Select V2

View code

Vue

<template>
	<div class="demo-stack">
		<FaSelectV2
			v-model="value"
			v-model:label="label"
			:data="data"
			multiple
			filterable
			more-detail
			clearable
			placeholder="从 1000 项中筛选"
			style="max-width: 480px"
			@change="changedData = $event"
		>
			<template #default="{ item }">
				<div class="demo-option-detail">
					<strong>{{ item.label }}</strong
					><small>{{ item["group"] }}</small>
				</div>
			</template>
		</FaSelectV2>
		<span class="demo-value"
			>值：{{ JSON.stringify(value) }}；标签：{{ JSON.stringify(label) }}；change 数据：{{ JSON.stringify(changedData) }}</span
		>
	</div>
</template>

<script setup lang="ts">
import { ref } from "vue";

const value = ref<number[]>([]);
const label = ref<string[] | null>([]);
const changedData = ref<unknown>();
const data = Array.from({ length: 1000 }, (_, index) => ({
	value: index + 1,
	label: `虚拟选项 ${String(index + 1).padStart(4, "0")}`,
	group: `分组 ${Math.floor(index / 100) + 1}`,
}));
</script>

FaSelectV2 Complete API

Props (65)

Fast and Element Plus 2.14.6 props are merged below. Fast changes appear first; native props that are not forwarded remain visible for compatibility review.

Property	Source	Description	Type	Default
collapseTags	Fast override	Collapse tags in multiple selection.	Boolean	FasttrueELfalse
collapseTagsTooltip	Fast override	Show collapsed tags in a tooltip.	Boolean	FasttrueELfalse
itemHeight	Fast override	Virtual-list option height.	Number	Fast34EL34
loading	Fast override	Loading state.	Boolean	FastfalseELfalse
loadingText	Fast override	Text shown while remote data loads.	String	Fast加载中...EL—
modelValue	Fast override	v-model value.	String / Number / Boolean / Object / Array	FastfalseELfalse
noDataText	Fast override	Text when no options/nodes exist.	String	Fast暂无数据EL—
noMatchText	Fast override	Text when filtering finds no matches.	String	Fast暂无匹配的数据EL—
options	Fast override	Virtual-selector options.	Array	Fast—EL—
popperClass	Fast override	Custom dropdown-overlay class.	String	Fast""ELfalse
props	Fast override	Field mappings.	Object	Fast{"label":"label","value":"value","disabled":"disabled","options":"options"}EL{"label":"label","value":"value","disabled":"disabled","options":"options"}
label	Fast addition	Display text or synchronized label.	String / Array	—
width	Fast addition	Component width.	String / Number	100%
moreDetail	Fast addition	Enable wider option-detail layout.	Boolean	false
lazy	Fast addition	Enable lazy loading.	Boolean	true
defaultSelected	Fast addition	Initialize selection from the current value.	Boolean	false
data	Fast addition	Component data.	Array	[]
pageResult	Fast addition	Pagination data.	Boolean	false
requestApi	Fast addition	Asynchronous data-request function.	Function	—
initParam	Fast addition	Initial request parameters.	String / Number / Object	—
allowCreate	EL native	Allow creating new options.	Boolean	false
autocomplete	EL native	Native input autocomplete attribute.	String	none
automaticDropdown	EL native	Open dropdown automatically on focus.	Boolean	false
clearable	EL native	Allow clearing.	Boolean	false
clearIcon	EL native	Clear-button icon.	String / Object / Function	{"name":"CircleClose","__name":"circle-close"}
effect	EL native	Tooltip theme for the dropdown.	String	light
tagTooltip	EL native	Collapsed-tag tooltip options.	Object	{}
maxCollapseTags	EL native	Maximum visible tags before collapsing.	Number	1
defaultFirstOption	EL native	Select the first matching option on Enter.	Boolean	false
disabled	EL native	Disable the component or current option.	Boolean	false
estimatedOptionHeight	EL native	Controls virtual-list sizing mode: if undefined, the list uses fixed item height from item-height; if provided, the list uses dynamic item sizing and this value as the estimated item height.	Number	—
filterable	EL native	Allow filtering.	Boolean	false
filterMethod	EL native	Local option-filtering function.	Function	—
height	EL native	Component height.	Number	274
id	EL native	Native ID of the root input.	String	—
multiple	EL native	Allow multiple selection.	Boolean	false
multipleLimit	EL native	Maximum selections; 0 means unlimited.	Number	0
name	EL native	Icon name, CSS class, or external SVG URL.	String	—
remoteMethod	EL native	Loader called when remote-search keywords change.	Function	—
reserveKeyword	EL native	Keep the keyword after remote multiple selection.	Boolean	true
placeholder	EL native	Placeholder.	String	—
teleported	EL native	Teleport the dropdown to appendTo.	Boolean	true
persistent	EL native	Keep the hidden dropdown in the DOM.	Boolean	true
popperStyle	EL native	Custom dropdown-root styles.	String / Array / Object / Boolean	false
popperOptions	EL native	Popper positioning options.	Object	{}
remote	EL native	Enable remote search.	Boolean	false
debounce	EL native	Remote-search debounce in milliseconds.	Number	300
size	EL native	Component size.	String	—
valueKey	EL native	Unique key field for object-valued options.	String	value
scrollbarAlwaysOn	EL native	Controls whether the scrollbar is always displayed	Boolean	false
validateEvent	EL native	Trigger form validation on model changes.	Boolean	true
offset	EL native	Offset or overlay offset.	Number	12
remoteShowSuffix	EL native	Show the selector suffix icon in remote mode.	Boolean	false
showArrow	EL native	Show the dropdown arrow pointing to its trigger.	Boolean	true
placement	EL native	Preferred dropdown placement relative to its trigger.	String	bottom-start
fallbackPlacements	EL native	Fallback overlay placements tried in order.	Array	["bottom-start","top-start","right","left"]
tagType	EL native	Element Plus type for selection tags.	String	info
tagEffect	EL native	Element Plus effect for selection tags.	String	light
tabindex	EL native	Native input tabindex.	String / Number	0
appendTo	EL native	Overlay mount target.	String	—
fitInputWidth	EL native	Ensure dropdown width is at least the input width.	Boolean / Number	true
suffixIcon	EL native	Selector suffix icon.	String / Object / Function	{"name":"ArrowDown","__name":"arrow-down"}
emptyValues	EL native	Model values considered empty.	Array	—
valueOnClear	EL native	Value or factory used when clearing the model.	String / Number / Boolean / Function	false
ariaLabel	EL native	Accessible component name.	String	—

Events（10）

Name	Source	Description	Parameters / type
update:modelValue	EL native	Updates v-model.	—
change	EL native	Value or selection changes.	—
end-reached	EL native	Selector reaches a dropdown scroll boundary.	—
remove-tag	EL native	A multiple-selection tag is removed; receives the removed value.	—
visible-change	EL native	Selector dropdown visibility changes.	—
focus	EL native	Component gains focus.	—
blur	EL native	Component loses focus.	—
clear	EL native	Clear-button click after clearing completes.	—
update:label	Fast addition	Updates the label model.	—
dataChange	Fast addition	Asynchronous data loading completes.	—

Slots（8）

Name	Source	Description	Parameters / type
default	EL native	Default component content.	—
header	EL native	Custom header or table-header business content.	—
footer	EL native	Custom footer actions; overlays provide loading and close.	—
prefix	EL native	Custom selector input prefix.	—
empty	EL native	Custom empty-state content.	—
tag	EL native	Custom multiple-selection tags.	{ data: Option[], selectDisabled: boolean, deleteTag: (event: MouseEvent, option: Option) => void }
loading	EL native	Custom loading content.	—
label	EL native	Custom form, tree-node, or option label.	{ index: number, label: string | any, value: string | any }

Expose（9）

Name	Source	Description	Parameters / type
focus	EL native	Focuses the input/selector.	—
blur	EL native	Blurs the input/selector.	—
selectedLabel	EL native	Current selector display label.	—
loading	Fast addition	Fast business loading state.	—
refresh	Fast addition	Repeats the data request or refreshes business content.	—
setSelection	Fast addition	Sets the selector value and label.	—
clearSelection	Fast addition	Clears the current selection.	—
scrollTo	EL native	Scrolls the table/virtual list to a position.	—
resetScrollTop	EL native · not forwarded	Resets virtual-selector scroll to the top.	—

FaSelectV2 instance methods

focus Focus

Focuses the selector input.

Signature

focus(): void;

Example

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.focus();
</script>

Input

This method has no input parameters.

Returns

Value	Type	Description
result	void	No return value.

blur Blur

Blurs the selector input and hides the dropdown.

Signature

blur(): void;

Example

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.blur();
</script>

Input

This method has no input parameters.

Returns

Value	Type	Description
result	void	No return value.

scrollTo Scroll

Scrolls to the specified option index.

Signature

scrollTo(index: number): void;

Example

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.scrollTo(120);
</script>

Input

Input	Type	Required / default	Description
index	number	Required	Zero-based option index.

Returns

Value	Type	Description
result	void	No return value.

refresh Refresh

Refreshes.

Signature

refresh(): Promise<void>;

Example

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
const result = await componentRef.value?.refresh();
</script>

Input

This method has no input parameters.

Returns

Value	Type	Description
result	Promise<void>	Asynchronous result; callers handle Promise rejection.

setSelection Selection

Sets the selection.

Signature

setSelection(value: Exclude<ElSelectorModelValue, null | undefined>): void;

Example

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.setSelection(1);
</script>

Input

Input	Type	Required / default	Description
value	ElSelectorValue | ElSelectorValue[]	Required	Form value, selected value, or filter keyword to set.

Returns

Value	Type	Description
result	void	No return value.

clearSelection Selection

Clears the selection.

Signature

clearSelection(): void;

Example

<template>
	<FaSelectV2 ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaSelectV2 } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
componentRef.value?.clearSelection();
</script>

Input

This method has no input parameters.

Returns

Value	Type	Description
result	void	No return value.