Auto Complete

🌏 Translated with the assistance of DeepSeek and ChatGPT

A text input field with suggestions.

Basic Usage

Pass options as the list of choices. Provide modelValue for controlled mode.
Omit it or set it to undefined for uncontrolled mode; in this case you can supply a defaultValue as the initial value.

<template>
	<px-space direction="vertical">
		<px-auto-complete
			placeholder="Please input"
			v-model="input"
			:options="options"
		></px-auto-complete>
		<px-auto-complete
			placeholder="Please input"
			:options="options"
			default-value="test"
		></px-auto-complete>
	</px-space>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const input = ref('')

const options = ref<string[]>([
	'pear',
	'plum',
	'cherry',
	'blueberry',
	'raspberry',
	'blackberry',
	'lemon',
	'lime',
	'pomegranate',
	'apricot'
])
</script>

<style lang="css" scoped>
.px-auto-complete {
	width: 320px;
}
</style>

Disabled Options

Inside options, set disabled: true on any choice to disable it.

<template>
	<px-auto-complete
		placeholder="Please input"
		v-model="input"
		:options="options"
	></px-auto-complete>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const input = ref('')

const options = ref(
	[
		'apple',
		'banana',
		'orange',
		'grape',
		'strawberry',
		'kiwi',
		'mango',
		'pineapple',
		'watermelon',
		'peach'
	].map((item, index) => {
		return {
			label: item,
			value: item,
			disabled: (index & 1) === 1
		}
	})
)
</script>

<style lang="css" scoped>
.px-auto-complete {
	width: 320px;
}
</style>

Grouping

options also accepts option groups.

<template>
	<px-auto-complete
		placeholder="Please input"
		v-model="input"
		:options="options"
	></px-auto-complete>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const input = ref('')
const options = ref([
	{
		type: 'group',
		label: 'tropical fruits',
		children: [
			{ label: 'mango', value: 'mango' },
			{ label: 'pineapple', value: 'pineapple' },
			{ label: 'papaya', value: 'papaya' },
			{ label: 'dragon fruit', value: 'dragon fruit' },
			{ label: 'durian', value: 'durian' },
			{ label: 'lychee', value: 'lychee' },
			{ label: 'longan', value: 'longan' }
		]
	},
	{
		type: 'group',
		label: 'citrus fruits',
		children: [
			{ label: 'orange', value: 'orange' },
			{ label: 'lemon', value: 'lemon' },
			{ label: 'lime', value: 'lime' },
			{ label: 'grapefruit', value: 'grapefruit' },
			{ label: 'tangerine', value: 'tangerine' }
		]
	}
])
</script>

<style lang="css" scoped>
.px-auto-complete {
	width: 320px;
}
</style>

Remote Loading

Set the loading and showPopoverEmpty props and listen to the input event to reflect remote-loading UI states.

<template>
	<px-auto-complete
		placeholder="Please input"
		v-model="input"
		:options="options"
		:loading="loading"
		append
		@input="inputHandler"
	></px-auto-complete>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const input = ref('')
const loading = ref(false)

const options = ref<string[]>([])

const data = [
	'pear',
	'plum',
	'cherry',
	'blueberry',
	'raspberry',
	'blackberry',
	'lemon',
	'lime',
	'pomegranate',
	'apricot'
]

const inputHandler = () => {
	options.value = []
	loading.value = true
	setTimeout(() => {
		options.value = data
		loading.value = false
	}, 6000)
}
</script>

<style lang="css" scoped>
.px-auto-complete {
	width: 320px;
}
</style>

Append Mode

After selecting an option, append it to the existing input instead of replacing the content by enabling the append prop.
Use the filter and shouldShowPopover functions to control which options appear and when the popover is shown.

<template>
	<px-auto-complete
		placeholder="Please input"
		v-model="input"
		:options="options"
		:filter="filter"
		:shouldShowPopover="shouldShowPopover"
		append
	></px-auto-complete>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const input = ref('')

const options = ref<string[]>(['gmail.com', '163.com', 'qq.com'])

const filter = (_: string, options: string[]) => {
	return options
}
const shouldShowPopover = (value: string) => {
	return value.endsWith('@')
}
</script>

<style lang="css" scoped>
.px-auto-complete {
	width: 320px;
}
</style>

Custom Rendering

option slot customizes option rendering, group-label slot customizes group label rendering.

<template>
	<px-auto-complete placeholder="Please input" v-model="input" :options="options">
		<template #group-label="{ option }">
			{{ option.label }}
			<div
				style="margin-left: 12px; color: red; font-size: 16px"
				v-if="option.label === 'citrus fruits'"
			>
				HOT!
			</div>
		</template>
		<template #option="{ option }">
			{{ option.label }}
			<px-tag style="margin-left: 12px" v-if="option.value === 'orange'">NEW!</px-tag>
		</template>
	</px-auto-complete>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const input = ref('')
const options = ref([
	{
		type: 'group',
		label: 'citrus fruits',
		children: [
			{ label: 'orange', value: 'orange' },
			{ label: 'lemon', value: 'lemon' },
			{ label: 'lime', value: 'lime' },
			{ label: 'grapefruit', value: 'grapefruit' },
			{ label: 'tangerine', value: 'tangerine' }
		]
	},
	{
		type: 'group',
		label: 'tropical fruits',
		children: [
			{ label: 'mango', value: 'mango' },
			{ label: 'pineapple', value: 'pineapple' },
			{ label: 'papaya', value: 'papaya' },
			{ label: 'dragon fruit', value: 'dragon fruit' },
			{ label: 'durian', value: 'durian' },
			{ label: 'lychee', value: 'lychee' },
			{ label: 'longan', value: 'longan' }
		]
	}
])
</script>

<style lang="css" scoped>
.px-auto-complete {
	width: 320px;
}
</style>

More Options

This AutoComplete has most of Input component's features.

Disabled, Readonly, Loading & Clearable

Shape

Size

Slot

prefix

suffix

Composite

Status

Expose

<template>
	<px-space direction="vertical">
		<h4>Disabled, Readonly, Loading & Clearable</h4>
		<px-space>
			<px-auto-complete
				placeholder="Please input"
				disabled
				:options="options"
			></px-auto-complete>
			<px-auto-complete
				placeholder="Please input"
				readonly
				:options="options"
			></px-auto-complete>
			<px-auto-complete
				placeholder="Please input"
				loading
				:options="options"
			></px-auto-complete>
			<px-auto-complete
				placeholder="Please input"
				clearable
				:options="options"
			></px-auto-complete>
		</px-space>
		<h4>Shape</h4>
		<px-space>
			<px-auto-complete
				placeholder="Please input"
				shape="round"
				:options="options"
			></px-auto-complete>
			<px-auto-complete placeholder="Please input" :options="options"></px-auto-complete>
		</px-space>
		<h4>Size</h4>
		<px-space>
			<px-auto-complete
				placeholder="Please input"
				size="small"
				:options="options"
			></px-auto-complete>
			<px-auto-complete placeholder="Please input" :options="options"></px-auto-complete>
			<px-auto-complete
				placeholder="Please input"
				size="large"
				:options="options"
			></px-auto-complete>
		</px-space>
		<h4>Slot</h4>
		<px-space>
			<px-auto-complete placeholder="Please input" :options="options">
				<template #prefix>prefix</template>
				<template #suffix>suffix</template>
			</px-auto-complete>
			<px-auto-complete placeholder="Please input" :options="options">
				<template #prepend>
					<IconBolt></IconBolt>
				</template>
			</px-auto-complete>
			<px-auto-complete placeholder="Please input" :options="options">
				<template #append>
					<IconBolt></IconBolt>
				</template>
			</px-auto-complete>
		</px-space>
		<h4>Composite</h4>
		<px-space>
			<px-input-group>
				<px-input-group-label>
					<IconBolt></IconBolt>
				</px-input-group-label>
				<px-auto-complete placeholder="Please input" :options="options"> </px-auto-complete>
				<px-button>Confirm</px-button>
			</px-input-group>
		</px-space>
		<h4>Status</h4>
		<px-space>
			<px-auto-complete placeholder="Please input" :options="options"> </px-auto-complete>
			<px-auto-complete placeholder="Please input" :options="options" status="success">
			</px-auto-complete>
			<px-auto-complete placeholder="Please input" :options="options" status="warning">
			</px-auto-complete>
			<px-auto-complete placeholder="Please input" :options="options" status="error">
			</px-auto-complete>
		</px-space>
		<h4>Expose</h4>
		<px-space direction="vertical">
			<px-space>
				<px-button theme="info" @click="focusHandler">Focus</px-button>
				<px-button theme="info" @click="blurHandler">Blur</px-button>
				<px-button theme="info" @click="selectHandler">Select</px-button>
				<px-button theme="warning" @click="clearHandler">Clear</px-button>
			</px-space>
			<px-auto-complete
				placeholder="Please input"
				:options="options"
				ref="autoCompleteRef"
			></px-auto-complete>
		</px-space>
	</px-space>
</template>

<script setup lang="ts">
import { IconBolt } from '@pixelium/web-vue/icon-hn/es'
import { ref } from 'vue'
import { AutoComplete } from '@pixelium/web-vue'

// If on-demand import
// import { AutoComplete } from '@pixelium/web-vue/es'

const autoCompleteRef = ref<InstanceType<typeof AutoComplete>>(null)

const focusHandler = () => {
	autoCompleteRef.value?.focus()
}
const blurHandler = () => {
	autoCompleteRef.value?.blur()
}
const clearHandler = () => {
	autoCompleteRef.value?.clear()
}
const selectHandler = () => {
	autoCompleteRef.value?.select()
}

const options = ref<string[]>([
	'pear',
	'plum',
	'cherry',
	'blueberry',
	'raspberry',
	'blackberry',
	'lemon',
	'lime',
	'pomegranate',
	'apricot'
])
</script>

<style lang="css" scoped>
.px-auto-complete {
	width: 320px;
}
</style>

API

AutoCompleteProps

Attribute	Type	Optional	Default	Description	Version
modelValue	`string \| null`	True		Value of the auto complete input (controlled mode), supports `v-model`.	0.0.2
defaultValue	`string \| null`	True		Default value of the auto complete input (uncontrolled mode).	0.0.2
options	`string`	True		List of options.	0.0.2
placeholder	`string`	True		Placeholder text.	0.0.2
disabled	`boolean`	True	`false`	Whether the input is disabled.	0.0.2
readonly	`boolean`	True	`false`	Whether the input is read-only.	0.0.2
clearable	`boolean`	True	`false`	Whether to show a clear button.	0.0.2
loading	`boolean`	True	`false`	Whether to show a loading state.	0.0.2
showPopoverEmpty	`boolean`	True	`false`	Whether to display the popover when the options list is empty.	0.0.2
shouldShowPopover	`(value: string, optionsFiltered: (string \| AutoCompleteOption \| AutoCompleteGroupOption)[]) => boolean`	True		Function to determine whether to show the popover while inputting.	0.0.2
filter	`(keyword: string, options: (string \| AutoCompleteOption \| AutoCompleteGroupOption)[]) => (string \| AutoCompleteOption \| AutoCompleteGroupOption)[]`	True		Function to filter the options.	0.0.2
append	`boolean`	True	`false`	Append mode.	0.0.2
size	`'medium' \| 'large' \| 'small'`	True	`'medium'`	Size of the auto complete input.	0.0.2
shape	`'default' \| 'round'`	True	`'default'`	Shape of the auto complete input.	0.0.2
borderRadius	`NumberOrPercentage \| NumberOrPercentage[]`	True			0.0.2
status	`'success' \| 'warning' \| 'error' \| 'normal'`	True	`'normal'`	Form validation status.	0.0.2
autofocus	`boolean`	True	`false`	Native `<input>` `autofocus` attribute.	0.0.2

AutoCompleteEvents

Event	Parameter	Description	Version
input	`value: string, e: Event`	Callback fired when the input value changes.	0.0.2
update:modelValue	`value: string`	Callback fired when `modelValue` is updated.	0.0.2
change	`value: string, e: Event \| undefined`	Callback fired when the input content changes.	0.0.2
clear	`value: string`	Callback fired when the clear button is clicked.	0.0.2
blur	`e: FocusEvent`	Callback fired when the input loses focus.	0.0.2
focus	`e: FocusEvent`	Callback fired when the input receives focus.	0.0.2
select	`value: string, option: string \| AutoCompleteOption, e: MouseEvent`	Callback fired when an option is selected.	0.0.2

AutoCompleteSlots

Slot	Parameter	Description	Version
prefix		Prefix content.	0.0.2
suffix		Suffix content.	0.0.2
option	`option: string \| AutoCompleteOption`	Custom option content.	0.0.2
group-label	`option: AutoCompleteGroupOption`	Label for option groups.	0.0.2

AutoCompleteExpose

Attribute	Type	Optional	Description	Version
focus	`() => void`	False	Focus the control.	0.0.2
blur	`() => void`	False	Blur the control.	0.0.2
clear	`() => void`	False	Clear the current input.	0.0.2
select	`() => void`	False	Select all text in the input.	0.0.2

AutoCompleteOption, AutoCompleteGroupOption

export interface Option<T = any> {
	value: T
	label: string
}

export interface GroupOption<T = any> {
	children: (Option<T> | string)[]
	type: typeof GROUP_OPTION_TYPE
}

export interface AutoCompleteOption extends Option<string> {
	value: string
	disabled?: boolean
}

export interface AutoCompleteGroupOption extends GroupOption {
	label: string
	key: string | number | symbol
	children: (AutoCompleteOption | string)[]
}

Auto Complete ​

Basic Usage ​

Disabled Options ​

Grouping ​

Remote Loading ​

Append Mode ​

Custom Rendering ​

More Options ​