VfSmartSelect

Advanced searchable select component with filtering, keyboard navigation, grouping, and async data loading.

Import

import { VfSmartSelect } from '@zyno-io/vue-foundation';

Basic Usage

<VfSmartSelect v-model="selectedUser" :options="users" :label-field="'name'" :value-field="'id'" placeholder="Select a user..." null-title="None" />

Props

Prop	Type	Description
modelValue	V | null	Selected value (v-model)
options	T[]	Static options array
loadOptions	(search: string | null) => Promise<T[]>	Async option loader
preload	boolean	Load options immediately on mount
remoteSearch	boolean	Reload options on each search (debounced 250ms)
keyField	keyof T	Field used as unique key
keyExtractor	(option: T) => string | symbol	Custom key extraction
valueField	keyof T	Field used as the emitted value
valueExtractor	(option: T) => V	Custom value extraction
labelField	keyof T	Field displayed as option text
formatter	(option: T) => string	Custom display formatter
selectionFormatter	(option: T) => string	Custom formatter for the selected value in the input
subtitleFormatter	(option: T) => string	Format subtitle text below option
classForOption	(option: T) => string	CSS class per option
groupField	keyof T	Field to group options by
groupFormatter	(option: T) => string	Custom group label formatter
searchFields	(keyof T)[]	Fields to search (defaults to title + subtitle)
prependOptions	T[]	Options prepended to the list
appendOptions	T[]	Options appended to the list
onCreateItem	(text: string) => void	Enable "Create ..." option when no match
showCreateTextOnNewItem	boolean	Show "Create <text>..." label (default: true)
nullTitle	string	Text for the null/deselect option
noResultsText	string	Text when search has no matches
placeholder	string	Input placeholder text
loadingText	string	Placeholder while loading
disabled	boolean	Disable the select
required	boolean	HTML required attribute
name	string	HTML name attribute
autoNext	boolean	Focus next input after selection
debug	boolean	Keep options open on blur (development aid)

Events

Event	Description
update:modelValue	Emitted when the selected value changes
optionsLoaded	Emitted after async options finish loading

Slots

<VfSmartSelect v-model="value" :options="items">
    <!-- Custom option rendering -->
    <template #option="{ option }">
        <div class="custom-option">
            <img :src="option.ref.avatar" />
            <span>{{ option.title }}</span>
        </div>
    </template>

    <!-- Custom group header -->
    <template #group="{ group }">
        <strong>{{ group }}</strong>
    </template>

    <!-- Custom no-results message -->
    <template #no-results>
        No matches. Try a different search.
    </template>
</VfSmartSelect>

Exposed Methods

const selectRef = ref();
selectRef.value.addRemoteOption(newOption); // Add option to remote options list

Features

• Search text highlighting via mark.js
• Keyboard navigation (Arrow keys, Page Up/Down, Home/End, Enter, Escape)
• Option list teleported to body for proper z-index stacking
• Automatic scroll management for highlighted options

Demos

Basic (label-field + value-field)

<template>
    <div data-testid="demo-ss-basic" style="max-width: 320px">
        <VfSmartSelect v-model="value" :options="options" :label-field="'label'" :value-field="'value'" placeholder="Pick a fruit or vegetable..." />
        <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ value ?? 'none' }}</span>
    </div>
</template>

<script lang="ts" setup>
import { VfSmartSelect } from '@zyno-io/vue-foundation';
import { ref } from 'vue';

const options = [
    { value: '1', label: 'Apple', group: 'Fruits' },
    { value: '2', label: 'Banana', group: 'Fruits' },
    { value: '3', label: 'Cherry', group: 'Fruits' },
    { value: '4', label: 'Carrot', group: 'Vegetables' },
    { value: '5', label: 'Broccoli', group: 'Vegetables' },
    { value: '6', label: 'Spinach', group: 'Vegetables' }
];

const value = ref<string | null>(null);
</script>

Grouped with null-title (deselect)

<template>
    <div data-testid="demo-ss-grouped" style="max-width: 320px">
        <VfSmartSelect
            v-model="value"
            :options="options"
            :label-field="'label'"
            :value-field="'value'"
            :group-field="'group'"
            null-title="Clear selection"
        />
        <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ value ?? 'none' }}</span>
    </div>
</template>

<script lang="ts" setup>
import { VfSmartSelect } from '@zyno-io/vue-foundation';
import { ref } from 'vue';

const options = [
    { value: '1', label: 'Apple', group: 'Fruits' },
    { value: '2', label: 'Banana', group: 'Fruits' },
    { value: '3', label: 'Cherry', group: 'Fruits' },
    { value: '4', label: 'Carrot', group: 'Vegetables' },
    { value: '5', label: 'Broccoli', group: 'Vegetables' },
    { value: '6', label: 'Spinach', group: 'Vegetables' }
];

const value = ref<string | null>(null);
</script>

Full object value (no value-field)

When value-field is omitted, the entire option object is emitted as the model value.

<template>
    <div data-testid="demo-ss-object" style="max-width: 320px">
        <VfSmartSelect v-model="value" :options="options" :label-field="'label'" placeholder="Select an option..." />
        <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ value ? value.label : 'none' }}</span>
    </div>
</template>

<script lang="ts" setup>
import { VfSmartSelect } from '@zyno-io/vue-foundation';
import { ref } from 'vue';

interface IOption {
    label: string;
    value: string;
}

const options: IOption[] = [
    { value: '1', label: 'Apple' },
    { value: '2', label: 'Banana' },
    { value: '3', label: 'Cherry' }
];

const value = ref<IOption | null>(null);
</script>

Custom formatter + value-extractor

Use formatter and value-extractor functions instead of field names for full control.

<template>
    <div data-testid="demo-ss-formatter" style="max-width: 320px">
        <VfSmartSelect
            v-model="value"
            :options="options"
            :formatter="o => `${o.label} (${o.group})`"
            :value-extractor="o => o.value"
            placeholder="Select..."
        />
        <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ value ?? 'none' }}</span>
    </div>
</template>

<script lang="ts" setup>
import { VfSmartSelect } from '@zyno-io/vue-foundation';
import { ref } from 'vue';

const options = [
    { value: '1', label: 'Apple', group: 'Fruits' },
    { value: '2', label: 'Banana', group: 'Fruits' },
    { value: '3', label: 'Carrot', group: 'Vegetables' }
];

const value = ref<string | null>(null);
</script>

Preselected value

<template>
    <div data-testid="demo-ss-preselected" style="max-width: 320px">
        <VfSmartSelect v-model="value" :options="options" :label-field="'label'" :value-field="'value'" />
        <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ value }}</span>
    </div>
</template>

<script lang="ts" setup>
import { VfSmartSelect } from '@zyno-io/vue-foundation';
import { ref } from 'vue';

const options = [
    { value: '1', label: 'Apple' },
    { value: '2', label: 'Banana' },
    { value: '3', label: 'Cherry' }
];

const value = ref<string | null>('2');
</script>

Delayed options (loading state)

When options is initially undefined, the select shows loading-text until options are provided.

<template>
    <div data-testid="demo-ss-delayed" style="max-width: 320px">
        <VfSmartSelect
            v-model="value"
            :options="delayedOptions"
            :label-field="'label'"
            :value-field="'value'"
            loading-text="Loading options..."
            null-title="No selection"
        />
        <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ value ?? 'none' }} (options load after 1.5s)</span>
    </div>
</template>

<script lang="ts" setup>
import { VfSmartSelect } from '@zyno-io/vue-foundation';
import { onMounted, ref } from 'vue';

const options = [
    { value: '1', label: 'Apple' },
    { value: '2', label: 'Banana' },
    { value: '3', label: 'Cherry' }
];

const delayedOptions = ref<typeof options>();
const value = ref<string | null>(null);

onMounted(() => {
    setTimeout(() => {
        delayedOptions.value = [...options];
    }, 1500);
});
</script>

Async loadOptions

Use load-options for async data fetching. With preload, options load on mount. Without it, they load on first open.

<template>
    <div data-testid="demo-ss-async" style="display: flex; flex-direction: column; gap: 16px; max-width: 320px">
        <div data-testid="async-preload">
            <span style="display: block; margin-bottom: 4px; font-size: 13px; font-weight: 600">With preload</span>
            <VfSmartSelect
                v-model="preloadValue"
                :load-options="loadOptions"
                :label-field="'label'"
                :value-field="'value'"
                preload
                loading-text="Fetching..."
            />
            <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ preloadValue ?? 'none' }}</span>
        </div>

        <div data-testid="async-lazy">
            <span style="display: block; margin-bottom: 4px; font-size: 13px; font-weight: 600">Lazy (no preload)</span>
            <VfSmartSelect
                v-model="lazyValue"
                :load-options="loadOptions"
                :label-field="'label'"
                :value-field="'value'"
                placeholder="Click to load..."
            />
            <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ lazyValue ?? 'none' }} (loads on first open)</span>
        </div>
    </div>
</template>

<script lang="ts" setup>
import { VfSmartSelect } from '@zyno-io/vue-foundation';
import { ref } from 'vue';

interface IOption {
    label: string;
    value: string;
}

const preloadValue = ref<string | null>(null);
const lazyValue = ref<string | null>(null);

async function loadOptions(): Promise<IOption[]> {
    await new Promise(resolve => setTimeout(resolve, 800));
    return [
        { value: 'a', label: 'Async Option A' },
        { value: 'b', label: 'Async Option B' },
        { value: 'c', label: 'Async Option C' }
    ];
}
</script>

Create item

Pass on-create-item to allow creating new options when no search match is found.

<template>
    <div data-testid="demo-ss-create" style="max-width: 320px">
        <VfSmartSelect
            v-model="value"
            :options="effectiveOptions"
            :formatter="o => o.label"
            :value-extractor="o => o.value"
            :on-create-item="handleCreate"
            placeholder="Search or type to create..."
        />
        <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ value ?? 'none' }}</span>
    </div>
</template>

<script lang="ts" setup>
import { VfSmartSelect } from '@zyno-io/vue-foundation';
import { computed, ref } from 'vue';

interface IOption {
    label: string;
    value: string;
}

const options: IOption[] = [
    { value: '1', label: 'Apple' },
    { value: '2', label: 'Banana' },
    { value: '3', label: 'Cherry' }
];

const value = ref<string | null>(null);
const createdLabel = ref<string>();

const effectiveOptions = computed<IOption[]>(() => {
    if (createdLabel.value) {
        return [{ value: 'new', label: createdLabel.value }, ...options];
    }
    return options;
});

function handleCreate(text: string) {
    createdLabel.value = text;
    value.value = 'new';
}
</script>

Disabled

<template>
    <div data-testid="demo-ss-disabled" style="max-width: 320px">
        <VfSmartSelect v-model="value" :options="options" :label-field="'label'" :value-field="'value'" disabled />
        <span class="result" style="font-size: 13px; color: var(--vp-c-text-2)">Selected: {{ value }}</span>
    </div>
</template>

<script lang="ts" setup>
import { VfSmartSelect } from '@zyno-io/vue-foundation';
import { ref } from 'vue';

const options = [
    { value: '1', label: 'Apple' },
    { value: '2', label: 'Banana' },
    { value: '3', label: 'Cherry' }
];

const value = ref<string | null>('2');
</script>