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.

Basic

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

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

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 (60)

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
modelValue	Fast override	v-model value.	String / Number / Boolean / Object / Array	FastfalseELfalse
loading	Fast override	Loading state.	Boolean	FastfalseELfalse
popperClass	Fast override	Custom dropdown-overlay class.	String / Array / Object / Boolean	Fast""EL""
props	Fast override	Field mappings.	Object	Fast{"label":"label","hide":"hide","disabled":"disabled","children":"children"}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	[]
requestApi	Fast addition	Asynchronous data-request function.	Function	—
initParam	Fast addition	Initial request parameters.	String / Number / Object	—
name	EL native	Icon name, CSS class, or external SVG URL.	String	—
id	EL native	Native ID of the root input.	String	—
autocomplete	EL native	Native input autocomplete attribute.	String	off
automaticDropdown	EL native	Open dropdown automatically on focus.	Boolean	false
size	EL native	Component size.	String	—
effect	EL native	Tooltip theme for the dropdown.	String	light
disabled	EL native	Disable the component or current option.	Boolean	false
clearable	EL native	Allow clearing.	Boolean	false
filterable	EL native	Allow filtering.	Boolean	false
allowCreate	EL native	Allow creating new options.	Boolean	false
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
loadingText	EL native	Text shown while remote data loads.	String	加载中...
noMatchText	EL native	Text when filtering finds no matches.	String	暂无匹配的数据
noDataText	EL native	Text when no options/nodes exist.	String	暂无数据
remoteMethod	EL native	Loader called when remote-search keywords change.	Function	—
filterMethod	EL native	Local option-filtering function.	Function	—
multiple	EL native	Allow multiple selection.	Boolean	false
multipleLimit	EL native	Maximum selections; 0 means unlimited.	Number	0
placeholder	EL native	Placeholder.	String	—
defaultFirstOption	EL native	Select the first matching option on Enter.	Boolean	false
reserveKeyword	EL native	Keep the keyword after remote multiple selection.	Boolean	true
valueKey	EL native	Unique key field for object-valued options.	String	value
collapseTags	EL native	Collapse tags in multiple selection.	Boolean	true
collapseTagsTooltip	EL native	Show collapsed tags in a tooltip.	Boolean	true
tagTooltip	EL native	Collapsed-tag tooltip options.	Object	{}
maxCollapseTags	EL native	Maximum visible tags before collapsing.	Number	1
teleported	EL native	Teleport the dropdown to appendTo.	Boolean	true
persistent	EL native	Keep the hidden dropdown in the DOM.	Boolean	true
clearIcon	EL native	Clear-button icon.	String / Object / Function	{"name":"CircleClose","__name":"circle-close"}
fitInputWidth	EL native	Ensure dropdown width is at least the input width.	Boolean	false
suffixIcon	EL native	Selector suffix icon.	String / Object / Function	{"name":"ArrowDown","__name":"arrow-down"}
tagType	EL native	Element Plus type for selection tags.	String	info
tagEffect	EL native	Element Plus effect for selection tags.	String	light
validateEvent	EL native	Trigger form validation on model changes.	Boolean	true
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
offset	EL native	Offset or overlay offset.	Number	12
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"]
tabindex	EL native	Native input tabindex.	String / Number	0
appendTo	EL native	Overlay mount target.	String / Object	—
options	EL native	Virtual-selector options.	Array	—
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（11）

Name	Source	Description	Parameters / type
update:modelValue	EL native	Updates v-model.	—
change	EL native	Value or selection changes.	—
popup-scroll	EL native	Selector dropdown scrolls.	—
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.	—
loading	EL native	Custom loading content.	—
label	EL native	Custom form, tree-node, or option label.	—

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 · not forwarded	Scrolls the table/virtual list to a position.	—
handleClose	EL native · not forwarded	Invokes Element Plus internal closing behavior.	—

Related component: FaSelectOption

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

FaSelectOption Complete API

Props (6)

Property	Source	Description	Type	Default
value	Fast addition	Option value; explicit values take precedence over data mappings.	String / Number / Boolean / Object	false
label	Fast addition	Display text or synchronized label.	String	—
disabled	Fast addition	Disable the component or current option.	Boolean	false
children	Fast addition	Child options in an option group.	Array	—
data	Fast addition	Component data.	Object	{}
moreDetail	Fast addition	Enable wider option-detail layout.	Boolean	false

Events（0）

Name	Source	Description	Parameters / type
No runtime Emits declarations.

Slots（1）

Name	Source	Description	Parameters / type
default(option)	Fast addition	Default component content.	(option)

Expose（0）

Name	Source	Description	Parameters / type
None.

FaSelect instance methods

focus Focus

Focuses the selector input.

Signature

focus(): void;

Example

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

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

const componentRef = ref<InstanceType<typeof FaSelect>>();
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>
	<FaSelect ref="componentRef" />
</template>

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

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

Input

This method has no input parameters.

Returns

Value	Type	Description
result	void	No return value.

refresh Refresh

Refreshes.

Signature

refresh(): Promise<void>;

Example

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

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

const componentRef = ref<InstanceType<typeof FaSelect>>();
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>
	<FaSelect ref="componentRef" />
</template>

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

const componentRef = ref<InstanceType<typeof FaSelect>>();
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>
	<FaSelect ref="componentRef" />
</template>

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

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

Input

This method has no input parameters.

Returns

Value	Type	Description
result	void	No return value.