Skip to content

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.

Since 2.0.28, options still come from data or requestApi. #tag receives { data, deleteTag, selectDisabled } and #label receives { label, value, index }.

Select V2

Interactive example
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

EL defaults refer to Element Plus before Fast is imported. 2.14.7

PropertySourceDescriptionTypeDefault
collapseTagsFast overrideCollapse tags in multiple selection.BooleanFasttrueELfalse
collapseTagsTooltipFast overrideShow collapsed tags in a tooltip.BooleanFasttrueELfalse
itemHeightFast overrideVirtual-list option height.NumberFast34EL34
loadingFast overrideLoading state.BooleanFastfalseELfalse
loadingTextFast overrideText shown while remote data loads.StringFast加载中...EL—
modelValueFast overridev-model value.String / Number / Boolean / Object / ArrayFastfalseELfalse
noDataTextFast overrideText when no options/nodes exist.StringFast暂无数据EL—
noMatchTextFast overrideText when filtering finds no matches.StringFast暂无匹配的数据EL—
optionsFast overrideVirtual-selector options.ArrayFast—EL—
popperClassFast overrideCustom dropdown-overlay class.StringFast""ELfalse
propsFast overrideField mappings.ObjectFast{"label":"label","value":"value","disabled":"disabled","options":"options"}EL{"label":"label","value":"value","disabled":"disabled","options":"options"}
labelFast additionDisplay text or synchronized label.String / Array—
widthFast additionComponent width.String / Number100%
moreDetailFast additionEnable wider option-detail layout.Booleanfalse
lazyFast additionEnable lazy loading.Booleantrue
defaultSelectedFast additionInitialize selection from the current value.Booleanfalse
dataFast additionComponent data.Array[]
pageResultFast additionPagination data.Booleanfalse
requestApiFast additionAsynchronous data-request function.Function—
initParamFast additionInitial request parameters.String / Number / Object—
allowCreateEL nativeAllow creating new options.Booleanfalse
autocompleteEL nativeNative input autocomplete attribute.Stringnone
automaticDropdownEL nativeOpen dropdown automatically on focus.Booleanfalse
clearableEL nativeAllow clearing.Booleanfalse
clearIconEL nativeClear-button icon.String / Object / Function{"name":"CircleClose","__name":"circle-close"}
effectEL nativeTooltip theme for the dropdown.Stringlight
tagTooltipEL nativeCollapsed-tag tooltip options.Object{}
maxCollapseTagsEL nativeMaximum visible tags before collapsing.Number1
defaultFirstOptionEL nativeSelect the first matching option on Enter.Booleanfalse
disabledEL nativeDisable the component or current option.Booleanfalse
estimatedOptionHeightEL nativeControls 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—
filterableEL nativeAllow filtering.Booleanfalse
filterMethodEL nativeLocal option-filtering function.Function—
heightEL nativeComponent height.Number274
idEL nativeNative ID of the root input.String—
multipleEL nativeAllow multiple selection.Booleanfalse
multipleLimitEL nativeMaximum selections; 0 means unlimited.Number0
nameEL nativeIcon name, CSS class, or external SVG URL.String—
remoteMethodEL nativeLoader called when remote-search keywords change.Function—
reserveKeywordEL nativeKeep the keyword after remote multiple selection.Booleantrue
placeholderEL nativePlaceholder.String—
teleportedEL nativeTeleport the dropdown to appendTo.Booleantrue
persistentEL nativeKeep the hidden dropdown in the DOM.Booleantrue
popperStyleEL nativeCustom dropdown-root styles.String / Array / Object / Booleanfalse
popperOptionsEL nativePopper positioning options.Object{}
remoteEL nativeEnable remote search.Booleanfalse
debounceEL nativeRemote-search debounce in milliseconds.Number300
sizeEL nativeComponent size.String—
valueKeyEL nativeUnique key field for object-valued options.Stringvalue
scrollbarAlwaysOnEL nativeControls whether the scrollbar is always displayedBooleanfalse
validateEventEL nativeTrigger form validation on model changes.Booleantrue
offsetEL nativeOffset or overlay offset.Number12
remoteShowSuffixEL nativeShow the selector suffix icon in remote mode.Booleanfalse
showArrowEL nativeShow the dropdown arrow pointing to its trigger.Booleantrue
placementEL nativePreferred dropdown placement relative to its trigger.Stringbottom-start
fallbackPlacementsEL nativeFallback overlay placements tried in order.Array["bottom-start","top-start","right","left"]
tagTypeEL nativeElement Plus type for selection tags.Stringinfo
tagEffectEL nativeElement Plus effect for selection tags.Stringlight
tabindexEL nativeNative input tabindex.String / Number0
appendToEL nativeOverlay mount target.String—
fitInputWidthEL nativeEnsure dropdown width is at least the input width.Boolean / Numbertrue
suffixIconEL nativeSelector suffix icon.String / Object / Function{"name":"ArrowDown","__name":"arrow-down"}
emptyValuesEL nativeModel values considered empty.Array—
valueOnClearEL nativeValue or factory used when clearing the model.String / Number / Boolean / Functionfalse
ariaLabelEL nativeAccessible component name.String—

Events

NameSourceDescriptionParameters / type
update:modelValueEL nativeUpdates v-model.—
changeEL nativeValue or selection changes.—
end-reachedEL nativeSelector reaches a dropdown scroll boundary.—
remove-tagEL nativeA multiple-selection tag is removed; receives the removed value.—
visible-changeEL nativeSelector dropdown visibility changes.—
focusEL nativeComponent gains focus.—
blurEL nativeComponent loses focus.—
clearEL nativeClear-button click after clearing completes.—
update:labelFast additionUpdates the label model.—
dataChangeFast additionAsynchronous data loading completes.—

Slots

NameSourceDescriptionParameters / type
defaultEL nativeDefault component content.—
headerEL nativeCustom header or table-header business content.—
footerEL nativeCustom footer actions; overlays provide loading and close.—
prefixEL nativeCustom selector input prefix.—
emptyEL nativeCustom empty-state content.—
tagEL nativeCustom multiple-selection tags.{ data: Option[], selectDisabled: boolean, deleteTag: (event: MouseEvent, option: Option) => void }
loadingEL nativeCustom loading content.—
labelEL nativeCustom form, tree-node, or option label.{ index: number, label: string | any, value: string | any }

Exposes

NameSourceDescriptionParameters / type
focusEL nativeFocuses the input/selector.—
blurEL nativeBlurs the input/selector.—
selectedLabelEL nativeCurrent selector display label.—
loadingFast additionFast business loading state.—
refreshFast additionRepeats the data request or refreshes business content.—
setSelectionFast additionSets the selector value and label.—
clearSelectionFast additionClears the current selection.—
scrollToEL nativeScrolls the table/virtual list to a position.—
resetScrollTopEL native · not forwardedResets virtual-selector scroll to the top.—

FaSelectV2 instance methods ​

These are call snippets. Use rows, options and fields from your actual data.

focus Focus ​

Focuses the selector input.

Signature ​

ts
focus(): void;

Example ​

vue
<template>
	<FaSelectV2 ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input: No parameters.

Returns: void.

blur Blur ​

Blurs the selector input and hides the dropdown.

Signature ​

ts
blur(): void;

Example ​

vue
<template>
	<FaSelectV2 ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input: No parameters.

Returns: void.

scrollTo Scroll ​

Scrolls to the specified option index.

Signature ​

ts
scrollTo(index: number): void;

Example ​

vue
<template>
	<FaSelectV2 ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
indexnumberRequiredZero-based option index.

Returns ​

ValueTypeDescription
resultvoidNo return value.

refresh Refresh ​

Refreshes.

Signature ​

ts
refresh(): Promise<void>;

Example ​

vue
<template>
	<FaSelectV2 ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

const componentRef = ref<InstanceType<typeof FaSelectV2>>();
async function handleExample() {
	const result = await componentRef.value?.refresh();
	console.log(result);
}
</script>

Input ​

This method has no input parameters.

Returns ​

ValueTypeDescription
resultPromise<void>Asynchronous result; callers handle Promise rejection.

setSelection Selection ​

Sets the selection.

Signature ​

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

Example ​

vue
<template>
	<FaSelectV2 ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
valueElSelectorValue | ElSelectorValue[]RequiredForm value, selected value, or filter keyword to set.

Returns ​

ValueTypeDescription
resultvoidNo return value.

clearSelection Selection ​

Clears the selection.

Signature ​

ts
clearSelection(): void;

Example ​

vue
<template>
	<FaSelectV2 ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input: No parameters.

Returns: void.