Autocomplete

Autocomplete is a search box with suggestions: type to filter, pick a suggestion to fill it, or press Enter to search the raw query.

Unlike Combobox (one value from a fixed list), the value of Autocomplete is free text and the suggestions only help fill it in. It filters ignoring diacritics (“xoai” finds “Xoài”), highlights matches, groups suggestions (recent searches, people, documents…), shows a loading state that follows Wait UX and announces the number of suggestions to screen readers. Keyboard: ↓/↑ move through suggestions, Enter picks one or searches, Esc closes the list (press again to clear the input).

Import

Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.

TSX

// npm install yugen-uiimport { Autocomplete } from "yugen-ui";

Variants

Each tile is a standalone example: hover to copy, or press Code to see the source.

Groups, icons & recent searches

minChars={0} opens the recent searches as soon as the input gets focus; suggestions can be disabled.

Suggestions from a server

filter={false} when the server has already filtered; loading shows a spinner if the wait passes 300ms.

Usage

Use it for search boxes with suggestions; use Combobox when people must pick exactly one value.
Limit the number of suggestions (maxSuggestions) and group them when there are several kinds of results.
Debounce and cancel stale requests when calling an API.

Don't

Don't fill the first suggestion into the input while people are typing.
Don't hide the Enter action: people must be able to search with their exact query.

Props

Prop · Type	Default	Description
suggestions(string \| AutocompleteSuggestion)[]	Default: —	Suggestions: value, label, description, icon, group, disabled.
filterboolean \| (s, query) => boolean	Default: true	Filters ignoring diacritics; false when the server has already filtered.
onSelect(s: AutocompleteSuggestion) => void	Default: —	Called when a suggestion is picked.
onSubmit(query: string) => void	Default: —	Called on Enter when no suggestion is active.
loadingboolean	Default: false	Suggestions are loading; the spinner appears after 300ms.
noResultsTextReactNode \| null	Default: "No matching suggestions"	Shown when no suggestions match; null closes the list instead. The old name emptyMessage is deprecated (removed in 1.0).
maxSuggestionsnumber	Default: 8	Maximum number of suggestions.
minCharsnumber	Default: 1	Characters needed before the list opens; 0 = open on focus.
highlightboolean	Default: true	Highlights the matching part.
listLabelstring	Default: "Search suggestions"	aria-label of the list.
value / defaultValue / onValueChangestring / (v: string) => void	Default: —	Query (controlled / uncontrolled).

Messages

Text built into the component: labels, aria-labels, screen reader announcements.

English by default. Change it with the messages prop of YugenProvider, by the namespace below; messagesVi has the Vietnamese set. See Interface language.

messages.autocomplete

Key · Type	Default (English)	messagesVi
emptystring Nội dung khi không có gợi ý nào khớp.	Default (English)`"No matching suggestions"`	messagesVi`"Không có gợi ý phù hợp"`
listLabelstring aria-label của danh sách gợi ý.	Default (English)`"Search suggestions"`	messagesVi`"Gợi ý tìm kiếm"`
searchingstring Chữ cạnh spinner khi đang tải gợi ý.	Default (English)`"Searching…"`	messagesVi`"Đang tìm…"`
count(count: number) => string Thông báo (aria-live) số gợi ý đang hiện.	Default (English)(count) => (count === 1 ? "1 suggestion" : `${count} suggestions`)	messagesVi(count) => `${count} gợi ý`