Chuyển tới nội dung

Pro đang mở bán trước. Cài đặt mở từ tháng 1/2027. Xem Pro

werewolf-ui
Component

Avatar

Hình tròn đại diện cho một người, team hoặc workspace: ảnh của họ, hoặc một hay hai chữ cái đầu trên cặp hue khi không có ảnh hoặc ảnh tải lỗi. Mặc định soft; solid bên trong Token hoặc trên ảnh hay gradient.

  • npm: 2 trực tiếp, 3 tổng
  • registry: 2 trực tiếp, 2 tổng

Xem trước

AL

Props

  • variant
  • color
  • size
  • photo
  • initials
  • icon
import { Avatar } from "@/components/ui/avatar"

const user = { name: "Ada Lovelace" }

<Avatar alt={user.name}>AL</Avatar>

Cách dùng

Khi nào dùng

  • Cho thấy nội dung thuộc về ai: tác giả comment, người được giao, các thành viên của một team.
  • Đứng thay ảnh thiếu hoặc chậm bằng một hoặc hai chữ cái đầu trên hue soft.

Khi nào không dùng

  • Logo, ảnh sản phẩm hoặc hình trong nội dung. Dùng img native.
  • Một người được chọn như một value, chẳng hạn người nhận trong một field. Dùng Token với avatar ở phía trước.
  • Một status như trực tuyến hoặc bận. Dùng Badge cạnh tên.
  • Nơi duy nhất một tên xuất hiện trong danh sách hoặc comment. Viết tên cạnh avatar.

Biến thể

variant

soft: background-<hue> với text-<hue>, cho danh sách và header comment. solid: nền solid <hue> với text-on-<hue>, bên trong Token hoặc trên ảnh hay gradient, nơi nền soft không nổi bật.

  • AL

    softmặc định

  • AL

    solid

import { Avatar } from "@/components/ui/avatar"

const user = { name: "Ada Lovelace" }

<Avatar alt={user.name}>AL</Avatar>
<Avatar variant="solid" alt={user.name}>AL</Avatar>

color

Cặp hue phía sau chữ cái đầu. Không bao giờ là accent. Để giữ một màu cho một người trên cả trang, chọn hue từ thứ ổn định, chẳng hạn user id của họ.

  • AL

    graymặc định

  • AL

    red

  • AL

    orange

  • AL

    yellow

  • AL

    green

  • AL

    teal

  • AL

    blue

  • AL

    purple

  • AL

    pink

import { Avatar } from "@/components/ui/avatar"

const user = { name: "Ada Lovelace" }

<Avatar alt={user.name}>AL</Avatar>
<Avatar color="red" alt={user.name}>AL</Avatar>
<Avatar color="orange" alt={user.name}>AL</Avatar>
<Avatar color="yellow" alt={user.name}>AL</Avatar>
<Avatar color="green" alt={user.name}>AL</Avatar>
<Avatar color="teal" alt={user.name}>AL</Avatar>
<Avatar color="blue" alt={user.name}>AL</Avatar>
<Avatar color="purple" alt={user.name}>AL</Avatar>
<Avatar color="pink" alt={user.name}>AL</Avatar>

size

sm 24px cho danh sách dày và hàng table, md 32px cho header comment và danh sách thành viên, lg 40px cho header hồ sơ.

  • AL

    sm

  • AL

    mdmặc định

  • AL

    lg

import { Avatar } from "@/components/ui/avatar"

const user = { name: "Ada Lovelace" }

<Avatar size="sm" alt={user.name}>AL</Avatar>
<Avatar alt={user.name}>AL</Avatar>
<Avatar size="lg" alt={user.name}>AL</Avatar>

Ví dụ

Mặc định

AL
import { Avatar } from "@/components/ui/avatar"

<Avatar alt="Ada Lovelace">AL</Avatar>

Có ảnh

Chữ cái đầu hiện đến khi ảnh tải xong, và ở lại nếu ảnh lỗi.

AL
import { Avatar } from "@/components/ui/avatar"

<Avatar src="/avatars/ada.jpg" alt="Ada Lovelace" color="blue">AL</Avatar>

Cạnh một tên

Tên được viết cạnh avatar, nên alt để trống và avatar bị ẩn khỏi trình đọc màn hình.

Grace Hopper
import { Avatar } from "@/components/ui/avatar"

<div className="flex items-center gap-sm">
  <Avatar alt="" color="teal" size="sm">GH</Avatar>
  <span className="text-sm text-text-primary">Grace Hopper</span>
</div>

Không có tên

Icon trên variant soft, cho khách hoặc tài khoản đã xóa.

import { IconUser } from "@tabler/icons-react"
import { Avatar } from "@/components/ui/avatar"

<Avatar alt="Khách">
  <IconUser size={16} />
</Avatar>

Nên và không nên

Nên

  • Truyền tên của người vào alt, hoặc alt="" khi tên được viết cạnh avatar.
  • Luôn truyền chữ cái đầu làm children, kể cả khi có src, để ảnh chậm hoặc hỏng vẫn còn gì đó để hiện.
  • Dùng solid bên trong Token hoặc trên ảnh hay gradient; dùng soft ở chỗ còn lại.
  • Giữ một hue cho mỗi người trên cả trang.

Không nên

  • Đừng đặt icon lên avatar solid; không có token icon cho nền hue solid.
  • Đừng dùng accent hoặc màu status làm nền.
  • Đừng để avatar thay tên nhìn thấy trong danh sách, comment hoặc field người được giao.
  • Đừng dùng nó cho logo hoặc ảnh sản phẩm; dùng img native.

Props

TênKiểuGiá trịMặc địnhMô tả
variantenumsoft | solidsoftsoft: background-<hue> với text-<hue>, cho danh sách và header comment. solid: nền solid <hue> với text-on-<hue>, bên trong Token hoặc trên ảnh hay gradient, nơi nền soft không nổi bật.
colorenumgray | red | orange | yellow | green | teal | blue | purple | pinkgrayCặp hue phía sau chữ cái đầu. Không bao giờ là accent. Để giữ một màu cho một người trên cả trang, chọn hue từ thứ ổn định, chẳng hạn user id của họ.
sizeenumsm | md | lgmdsm 24px cho danh sách dày và hàng table, md 32px cho header comment và danh sách thành viên, lg 40px cho header hồ sơ.
srcstring--URL của ảnh. Chữ cái đầu hiện cho đến khi ảnh tải xong, và ở lại nếu tải lỗi.
alt bắt buộcstring--Tên của người, team hoặc workspace: Ada Lovelace. Truyền chuỗi rỗng khi tên được viết cạnh avatar.

Slot

TênBắt buộcMô tả
fallbackcóMột hoặc hai chữ cái đầu, chẳng hạn AL. Trên variant soft, một icon cho người không có tên.

Cấu tạo

PhầnMô tả
rootHình tròn: radius-full, nền hue, và tên của avatar. 24, 32 hoặc 40px.
imageẢnh, được cắt để phủ kín hình tròn. Chỉ render sau khi đã tải xong, rồi hiện dần với duration-medium (không hiện dần khi giảm chuyển động).
fallbackChildren: một hoặc hai chữ cái đầu, weight medium, hiện cho đến khi ảnh tải xong và khi ảnh lỗi hoặc thiếu.
iconIcon Tabler tùy chọn làm fallback trên variant soft, 12px ở sm, 16px ở md, 20px ở lg.

Khả năng truy cập

Role: img

  • alt đặt tên cho avatar trên root (role img với aria-label), nên tên giữ nguyên dù ảnh tải được hay chữ cái đầu hiện ra, và chữ cái đầu không bị đọc rời từng chữ. Type bắt buộc có alt.
  • Khi tên được viết cạnh avatar, như ở header comment hoặc danh sách thành viên, truyền alt="": avatar bị ẩn khỏi trình đọc màn hình, nên tên không bị đọc hai lần.
  • Avatar không tương tác. Để mở một hồ sơ, đặt avatar và tên trong cùng một link, rồi đặt tên cho link.
  • Hue chỉ để trang trí. Đừng để nó tự mang nghĩa như vai trò hoặc status.
  • Chữ cái đầu trên solid dùng text-on-<hue>, đạt 4.5:1 trên mọi hue ở cả hai mode. Không có token icon cho nền hue solid, nên fallback bằng icon chỉ dành cho variant soft.

Cài đặt

npx werewolf-ui add avatar

Chạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.