Autocomplete

Autocomplete là ô tìm kiếm có gợi ý: gõ để lọc, chọn gợi ý để điền nhanh, hoặc Enter để tìm với nguyên từ khoá.

Khác Combobox (chọn một giá trị trong danh sách cố định), giá trị của Autocomplete là từ khoá tự do — gợi ý chỉ giúp điền nhanh. Lọc không dấu (gõ “xoai” ra “Xoài”), tô sáng phần khớp, nhóm gợi ý (Tìm gần đây, Người, Tài liệu…), trạng thái đang tải theo Wait UX và thông báo số gợi ý cho trình đọc màn hình. Bàn phím: ↓/↑ chọn gợi ý, Enter chọn hoặc tìm, Esc đóng danh sách (nhấn lần nữa để xoá ô).

Import

Cài từ npm, chép mã nguồn vào dự án bằng @yugen-ui/cli hoặc shadcn CLI, hoặc import thẳng khi làm việc trong repo này.

TSX

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

Biến thể

Mỗi ô là một mẫu độc lập: hover để Copy, hoặc bấm Code để xem mã nguồn.

Nhóm, icon & tìm gần đây

minChars={0} mở danh sách “Tìm gần đây” ngay khi focus; gợi ý có thể bị disabled.

Gợi ý từ server

filter={false} khi server đã lọc; loading hiện spinner nếu chờ quá 300ms.

Cách dùng

Nên

Dùng cho ô tìm kiếm có gợi ý; dùng Combobox khi người dùng phải chọn đúng một giá trị.
Giới hạn số gợi ý (maxSuggestions) và nhóm chúng khi có nhiều loại kết quả.
Debounce và huỷ request cũ khi gọi API.

Không nên

Không tự điền gợi ý đầu tiên vào ô khi người dùng đang gõ.
Không ẩn hành động Enter — người dùng phải tìm được với nguyên từ khoá.

Props

Prop · Kiểu	Mặc định	Mô tả
suggestions(string \| AutocompleteSuggestion)[]	Mặc định: —	Gợi ý: value, label, description, icon, group, disabled.
filterboolean \| (s, query) => boolean	Mặc định: true	Lọc không dấu; false khi server đã lọc.
onSelect(s: AutocompleteSuggestion) => void	Mặc định: —	Chọn một gợi ý.
onSubmit(query: string) => void	Mặc định: —	Enter khi không có gợi ý đang chọn.
loadingboolean	Mặc định: false	Đang tải gợi ý; spinner hiện sau 300ms.
noResultsTextReactNode \| null	Mặc định: "No matching suggestions"	Khi không có gợi ý khớp; null để đóng danh sách. Tên cũ emptyMessage đã lỗi thời (bỏ ở 1.0).
maxSuggestionsnumber	Mặc định: 8	Số gợi ý tối đa.
minCharsnumber	Mặc định: 1	Số ký tự trước khi mở; 0 = mở khi focus.
highlightboolean	Mặc định: true	Tô sáng phần khớp.
listLabelstring	Mặc định: "Search suggestions"	aria-label của danh sách.
value / defaultValue / onValueChangestring / (v: string) => void	Mặc định: —	Từ khoá (controlled / uncontrolled).

Messages

Chữ có sẵn của component: nhãn, aria-label, thông báo cho trình đọc màn hình.

Mặc định là tiếng Anh. Đổi qua prop messages của YugenProvider, theo namespace bên dưới; messagesVi chứa bản tiếng Việt. Xem Ngôn ngữ giao diện.

messages.autocomplete

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