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 exampleView code
<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 exampleView code
<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 exampleView code
<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
| 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"" |
loadingText | Fast global enhancement | Text shown while remote data loads. | String | Fast加载中...EL— |
noMatchText | Fast global enhancement | Text when filtering finds no matches. | String | Fast暂无匹配的数据EL— |
noDataText | Fast global enhancement | Text when no options/nodes exist. | String | Fast暂无数据EL— |
collapseTags | Fast global enhancement | Collapse tags in multiple selection. | Boolean | FasttrueELfalse |
collapseTagsTooltip | Fast global enhancement | Show collapsed tags in a tooltip. | Boolean | FasttrueELfalse |
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 |
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 |
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
| 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
| 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. | — |
Exposes
| 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.
Since 2.0.28, regular options pass created to the underlying ElOption.
FaSelectOption Complete API
Props
| 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 |
Slots
| Name | Source | Description | Parameters / type |
|---|---|---|---|
default(option) | Fast addition | Default 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
focus(): void;Example
<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
blur(): void;Example
<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
refresh(): Promise<void>;Example
<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
| 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" />
<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
| 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" />
<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.
