Autocomplete

Provides input suggestions based on input content.

Basic Usage

Use the fetch-suggestions prop to set the method for retrieving the suggestion list.

Basic Usage

Custom Template

Use the default slot to customize the display content of suggestion items.

Custom Template

Remote Search

Simulate fetching suggestion data from a server with delay.

Remote Search

Disabled State

Use the disabled prop to disable the input.

Disabled

Clearable

Use the clearable prop to quickly clear the content.

Clearable

Different Sizes

Supports large, default, and small sizes.

Different Sizes

Custom Slots

Use loading and empty slots to customize the content during loading and when there is no data.

Custom Slots

Use in Nuxt

The Autocomplete component works well in Nuxt 3/4 environments. With auto-import support, you can simply use the component name directly.

Use in Nuxt

SSR Notes:

• ✅ Initial state of the input (including v-model value) renders correctly on the server
• ✅ Size and placeholder support SSR
• ✅ Prefix and suffix slots generate HTML during the SSR phase
• ⚠️ The suggestion dropdown only appears during client-side interaction (input or focus), without affecting the initial HTML structure
• 💡 Debounce and dropdown positioning take effect after client-side activation (Hydration)

SSR Safety

The Autocomplete component internally wraps YhInput and the Popper system. It uses useId to ensure stability of the Input-to-dropdown association IDs during initial rendering, perfectly avoiding common ID conflict warnings under SSR.

API

Props

Prop	Description	Type	Default
model-value / v-model	Binding value	string	—
placeholder	Placeholder text	string	—
disabled	Whether disabled	boolean	false
clearable	Whether clearable	boolean	false
size	Input size	'large' | 'default' | 'small'	'default'
fetch-suggestions	Method to fetch suggestions	(query: string, callback: (suggestions: any[]) => void) => void	—
trigger-on-focus	Whether to trigger suggestions on focus	boolean	true
debounce	Debounce delay (ms)	number	300
placement	Dropdown position	'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'	'bottom-start'
value-key	Key name used for display in suggestion objects	string	'value'
highlight-first-item	Whether to highlight the first item by default	boolean	false
teleported	Whether to append the dropdown to body	boolean	true
fit-input-width	Whether the dropdown width matches the input	boolean	true
prefix-icon	Prefix icon	string | Component	—
suffix-icon	Suffix icon	string | Component	—
name	Native name attribute	string	—
autofocus	Auto focus	boolean	false
autocomplete	Native autocomplete attribute	string	'off'

Events

Event Name	Description	Parameters
input	Triggered when input value changes	(value: string) => void
change	Triggered when value changes	(value: string) => void
focus	Triggered on focus	(event: FocusEvent) => void
blur	Triggered on blur	(event: FocusEvent) => void
clear	Triggered when clear button is clicked	() => void
select	Triggered when a suggestion item is selected	(item: any) => void

Slots

Slot Name	Description	Scope
default	Custom suggestion item content	{ item: any }
prefix	Input prefix content	—
suffix	Input suffix content	—
prepend	Input prepend content	—
append	Input append content	—
loading	Content while loading	—
empty	Content when no data matches	—

Expose

Name	Description	Type
focus	Focus the input	() => void
blur	Blur the input	() => void
close	Close the suggestion list	() => void
highlight	Highlight a specified item	(index: number) => void

Theme Variables

The Autocomplete component uses the following CSS variables. You can customize styles by overriding these variables:

Variable	Description	Default
--yh-autocomplete-border-color	Border color	var(--yh-border-color)
--yh-autocomplete-hover-border-color	Hover border color	var(--yh-border-color-hover)
--yh-autocomplete-focus-border-color	Focus border color	var(--yh-color-primary)
--yh-autocomplete-disabled-bg-color	Disabled background color	var(--yh-fill-color-light)