Yugen UI

Avatar

Avatar đại diện cho một người hoặc một thực thể bằng ảnh, chữ cái đầu hoặc icon.

Luôn truyền name thật — dùng để sinh chữ cái đầu, màu (colorful) và nhãn cho trình đọc màn hình.

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

Kích thước

20, 24, 32 (mặc định), 40, 48, 64, 96.

Màu

neutral (mặc định), brand, colorful (màu ổn định theo hash của name).

Presence

available, busy, away, offline.

Shape

circular cho người; square cho nhóm, ứng dụng, bot.

Ảnh

src cho ảnh; ảnh không tải được thì quay về chữ viết tắt; square cho logo. image truyền srcSet, sizes, loading… vào thẻ <img>, renderImage dùng component ảnh của framework như <Image> của Next.js.

Cách dùng

Nên
  • Dùng color="colorful" khi có nhiều người cạnh nhau để dễ phân biệt.
  • Dùng square cho thực thể không phải người.
Không nên
  • Không truyền name rỗng hoặc giả.
  • Không tự đặt màu nền avatar bằng className.

Props

Prop · KiểuMặc địnhMô tả
namestringMặc định: —Bắt buộc. Sinh initials, màu và aria-label.
srcstringMặc định: —Ảnh đại diện; fallback về initials nếu lỗi.
image{ srcSet, sizes, loading, decoding, crossOrigin, referrerPolicy, fetchPriority }Mặc định: —Thuộc tính cho thẻ <img>. Tên vẫn nằm trên khung role="img".
renderImage(props) => ReactNodeMặc định: —Vẽ ảnh bằng component khác, vd. (props) => <Image {...props} width={48} height={48} /> của Next.js. Vẫn có chữ viết tắt khi ảnh lỗi.
onLoadingStatusChange(status: "loading" | "loaded" | "error") => voidMặc định: —Trạng thái tải ảnh, gọi lại cho mỗi src.
fallbackDelaynumberMặc định: 400Số ms chờ trước khi hiện chữ viết tắt trong lúc ảnh đang tải.
size20 | 24 | 32 | 40 | 48 | 64 | 96Mặc định: 32Kích thước px.
color"neutral" | "brand" | "colorful"Mặc định: "neutral"Bảng màu.
shape"circular" | "square"Mặc định: "circular"Hình dạng.
presence"available" | "busy" | "away" | "offline"Mặc định: —Chấm trạng thái.