TagPicker

TagPicker cho phép chọn nhiều mục, hiển thị mỗi mục là một Tag ngay trong ô nhập.

Gõ để lọc danh sách gợi ý (không phân biệt dấu), Enter để thêm, Backspace khi ô trống để gỡ tag cuối, mũi tên trái để di chuyển giữa các tag. Option đã chọn tự ẩn khỏi danh sách.

Thẻ bài viết

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 { TagPicker } 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.

Avatar & mô tả phụ

media hiện trên cả option và tag; size large dùng tag small vừa Avatar 20px.

Freeform

Gõ từ khoá mới rồi Enter để tạo tag.

2 thành viên được chọn

Controlled

value / onValueChange; tagAppearance và tagShape đổi kiểu tag.

Sắp xếp tag

reorderable: kéo tag, hoặc focus tag (← từ ô nhập) rồi Alt + ← → để đổi thứ tự. Bấm tag mà không kéo thì vẫn gỡ tag.

Kích thước

medium (tag extra-small), large (tag small), extra-large (tag medium).

Cách dùng

Nên

Dùng khi người dùng cần chọn nhiều mục và cần thấy rõ từng mục đã chọn.
Thêm Avatar/mô tả phụ khi chọn người để dễ phân biệt trùng tên.
Bật freeform cho từ khoá, email… không có sẵn trong danh sách.

Không nên

Không dùng cho lựa chọn đơn — dùng Combobox hoặc Dropdown.
Không để quá nhiều tag khiến ô cao vượt khỏi bố cục — cân nhắc giới hạn số lượng.

Props

Prop · Kiểu	Mặc định	Mô tả
options(string \| { value, label?, media?, secondaryText?, disabled?, group? })[]	Mặc định: —	Danh sách gợi ý.
value / defaultValuestring[]	Mặc định: —	Các giá trị đã chọn.
onValueChange(value: string[]) => void	Mặc định: —	Callback khi thêm/gỡ.
size"medium" \| "large" \| "extra-large"	Mặc định: "medium"	Chiều cao tối thiểu 32 / 40 / 48px.
appearance"outline" \| "underline" \| "filled-darker" \| "filled-lighter"	Mặc định: "outline"	Kiểu ô.
tagAppearance / tagShapeTagAppearance / TagShape	Mặc định: —	Kiểu của tag đã chọn.
freeformboolean	Mặc định: false	Enter để tạo tag từ văn bản tự gõ.
reorderableboolean	Mặc định: false	Kéo tag, hoặc Alt + phím mũi tên khi focus ở tag, để đổi thứ tự (Sortable).
noResultsTextReactNode	Mặc định: —	Hiện khi không còn gợi ý phù hợp.

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.tagPicker

Khoá · Kiểu	Mặc định (tiếng Anh)	messagesVi
noResultsstring Nội dung khi không có kết quả lọc.	Mặc định (tiếng Anh)`"No results found"`	messagesVi`"Không tìm thấy kết quả"`
addFreeform(query: string) => string Gợi ý khi `freeform` và chữ gõ không khớp option nào.	Mặc định (tiếng Anh)(query) => `Press Enter to add “${query}”`	messagesVi(query) => `Nhấn Enter để thêm “${query}”`
selectedItemsstring aria-label nhóm tag đã chọn.	Mặc định (tiếng Anh)`"Selected items"`	messagesVi`"Mục đã chọn"`
closeListstring aria-label nút mũi tên khi listbox đang mở.	Mặc định (tiếng Anh)`"Close list"`	messagesVi`"Đóng danh sách"`
openListstring aria-label nút mũi tên khi listbox đang đóng.	Mặc định (tiếng Anh)`"Open list"`	messagesVi`"Mở danh sách"`
listLabelstring Tên của listbox khi ô nhập không có nhãn hiển thị (Field nối nhãn qua aria-labelledby).	Mặc định (tiếng Anh)`"Suggestions"`	messagesVi`"Gợi ý"`