Skip to content

FaSelect ​

Retains native ElSelect filtering, multiple selection, option creation, remote search and slots. Adds object-data conversion, two-way label binding, lazy loading and explicit refresh.

Since 2.0.28, options still come from data or requestApi, with field mapping through valueKey and props. #tag receives { data, deleteTag, selectDisabled } and #label receives { label, value, index }.

Basic

Interactive example
View code
Vue
<template>
	<div class="demo-row">
		<FaSelect
			v-model="departmentId"
			v-model:label="departmentName"
			:data="departments"
			clearable
			filterable
			placeholder="选择部门"
			style="width: 240px"
		/>
		<FaSelect
			v-model="roles"
			v-model:label="roleNames"
			:data="departments"
			multiple
			clearable
			placeholder="选择多个部门"
			style="width: 300px"
			@change="changedRoleData = $event"
		/>
	</div>
	<p style="margin: 14px 0 0; color: var(--el-text-color-secondary)">
		当前值:{{ departmentId ?? "未选择" }};当前标签:{{ departmentName ?? "未选择" }}
	</p>
	<p style="margin: 6px 0 0; color: var(--el-text-color-secondary)">
		多选值:{{ JSON.stringify(roles) }};多选标签:{{ JSON.stringify(roleNames) }};change 数据:{{ JSON.stringify(changedRoleData) }}
	</p>
</template>

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

const departmentId = ref<number>();
const departmentName = ref<string | null>(null);
const roles = ref<number[]>([]);
const roleNames = ref<string[] | null>([]);
const changedRoleData = ref<unknown>();

const departments = [
	{ value: 1, label: "研发中心" },
	{ value: 2, label: "产品中心" },
	{ value: 3, label: "运营中心", disabled: true },
];
</script>

Field Mapping

Interactive example
View code
Vue
<template>
	<FaSelect
		v-model="value"
		:data="data"
		:props="{ label: 'name', disabled: 'locked', hide: 'hidden' }"
		value-key="id"
		more-detail
		clearable
		placeholder="选择部门"
		style="max-width: 420px"
	>
		<template #default="option">
			<div class="demo-option-detail">
				<strong>{{ option.label }}</strong
				><small>{{ option["description"] }}</small>
			</div>
		</template>
	</FaSelect>
</template>

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

const value = ref<number | null>(null);
const data = [
	{ id: 1, name: "平台研发部", locked: false, description: "负责 SDK 与基础设施" },
	{ id: 2, name: "业务研发部", locked: false, description: "负责业务应用交付" },
	{ id: 3, name: "归档部门", locked: true, description: "不可继续选择" },
	{ id: 4, name: "隐藏部门", hidden: true, description: "不会出现在下拉列表" },
];
</script>

Async Select

Interactive example
View code
Vue
<template>
	<div class="demo-row">
		<FaSelect ref="selectRef" v-model="value" :request-api="requestApi" clearable placeholder="首次展开时加载" style="width: 300px" />
		<ElButton :loading="selectRef?.loading" @click="selectRef?.refresh()">主动刷新</ElButton>
	</div>
</template>

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

interface SelectExpose {
	loading: boolean;
	refresh: () => Promise<void>;
}

const selectRef = useTemplateRef<SelectExpose>("selectRef");
const value = ref<number | null>(null);
let loadCount = 0;

const requestApi = async (): Promise<Record<string, unknown>[]> => {
	await new Promise<void>((resolve) => {
		window.setTimeout(resolve, 450);
	});
	loadCount++;
	return [
		{ value: 1, label: `研发中心(第 ${loadCount} 次加载)` },
		{ value: 2, label: "产品中心" },
		{ value: 3, label: "运营中心" },
	];
};
</script>

FaSelect Complete API

Props

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

PropertySourceDescriptionTypeDefault
modelValueFast overridev-model value.String / Number / Boolean / Object / ArrayFastfalseELfalse
loadingFast overrideLoading state.BooleanFastfalseELfalse
popperClassFast overrideCustom dropdown-overlay class.String / Array / Object / BooleanFast""EL""
loadingTextFast global enhancementText shown while remote data loads.StringFast加载中...EL—
noMatchTextFast global enhancementText when filtering finds no matches.StringFast暂无匹配的数据EL—
noDataTextFast global enhancementText when no options/nodes exist.StringFast暂无数据EL—
collapseTagsFast global enhancementCollapse tags in multiple selection.BooleanFasttrueELfalse
collapseTagsTooltipFast global enhancementShow collapsed tags in a tooltip.BooleanFasttrueELfalse
propsFast overrideField mappings.ObjectFast{"label":"label","hide":"hide","disabled":"disabled","children":"children"}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[]
requestApiFast additionAsynchronous data-request function.Function—
initParamFast additionInitial request parameters.String / Number / Object—
nameEL nativeIcon name, CSS class, or external SVG URL.String—
idEL nativeNative ID of the root input.String—
autocompleteEL nativeNative input autocomplete attribute.Stringoff
automaticDropdownEL nativeOpen dropdown automatically on focus.Booleanfalse
sizeEL nativeComponent size.String—
effectEL nativeTooltip theme for the dropdown.Stringlight
disabledEL nativeDisable the component or current option.Booleanfalse
clearableEL nativeAllow clearing.Booleanfalse
filterableEL nativeAllow filtering.Booleanfalse
allowCreateEL nativeAllow creating new options.Booleanfalse
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
remoteMethodEL nativeLoader called when remote-search keywords change.Function—
filterMethodEL nativeLocal option-filtering function.Function—
multipleEL nativeAllow multiple selection.Booleanfalse
multipleLimitEL nativeMaximum selections; 0 means unlimited.Number0
placeholderEL nativePlaceholder.String—
defaultFirstOptionEL nativeSelect the first matching option on Enter.Booleanfalse
reserveKeywordEL nativeKeep the keyword after remote multiple selection.Booleantrue
valueKeyEL nativeUnique key field for object-valued options.Stringvalue
tagTooltipEL nativeCollapsed-tag tooltip options.Object{}
maxCollapseTagsEL nativeMaximum visible tags before collapsing.Number1
teleportedEL nativeTeleport the dropdown to appendTo.Booleantrue
persistentEL nativeKeep the hidden dropdown in the DOM.Booleantrue
clearIconEL nativeClear-button icon.String / Object / Function{"name":"CircleClose","__name":"circle-close"}
fitInputWidthEL nativeEnsure dropdown width is at least the input width.Booleanfalse
suffixIconEL nativeSelector suffix icon.String / Object / Function{"name":"ArrowDown","__name":"arrow-down"}
tagTypeEL nativeElement Plus type for selection tags.Stringinfo
tagEffectEL nativeElement Plus effect for selection tags.Stringlight
validateEventEL nativeTrigger form validation on model changes.Booleantrue
remoteShowSuffixEL nativeShow the selector suffix icon in remote mode.Booleanfalse
showArrowEL nativeShow the dropdown arrow pointing to its trigger.Booleantrue
offsetEL nativeOffset or overlay offset.Number12
placementEL nativePreferred dropdown placement relative to its trigger.Stringbottom-start
fallbackPlacementsEL nativeFallback overlay placements tried in order.Array["bottom-start","top-start","right","left"]
tabindexEL nativeNative input tabindex.String / Number0
appendToEL nativeOverlay mount target.String / Object—
optionsEL nativeVirtual-selector options.Array—
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.—
popup-scrollEL nativeSelector dropdown scrolls.—
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.—
loadingEL nativeCustom loading content.—
labelEL nativeCustom form, tree-node, or option label.—

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 native · not forwardedScrolls the table/virtual list to a position.—
handleCloseEL native · not forwardedInvokes Element Plus internal closing behavior.—

Creates ElOption or ElOptionGroup from data, field mappings and explicit value, label, disabled and children. Explicit props take precedence over data fields.

Since 2.0.28, regular options pass created to the underlying ElOption.

FaSelectOption Complete API

Props

PropertySourceDescriptionTypeDefault
valueFast additionOption value; explicit values take precedence over data mappings.String / Number / Boolean / Objectfalse
labelFast additionDisplay text or synchronized label.String—
disabledFast additionDisable the component or current option.Booleanfalse
childrenFast additionChild options in an option group.Array—
dataFast additionComponent data.Object{}
moreDetailFast additionEnable wider option-detail layout.Booleanfalse

Slots

NameSourceDescriptionParameters / type
default(option)Fast additionDefault component content.(option)

FaSelect 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>
	<FaSelect ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

const componentRef = ref<InstanceType<typeof FaSelect>>();
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>
	<FaSelect ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input: No parameters.

Returns: void.

refresh Refresh ​

Refreshes.

Signature ​

ts
refresh(): Promise<void>;

Example ​

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

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

const componentRef = ref<InstanceType<typeof FaSelect>>();
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>
	<FaSelect ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

const componentRef = ref<InstanceType<typeof FaSelect>>();
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>
	<FaSelect ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input: No parameters.

Returns: void.