Chuyển tới nội dung
werewolf-ui
Component

Avatar

A circle that stands for a person, team or workspace: their photo, or one or two initials on a hue pair when there is no photo or it fails to load. Soft by default; solid inside a Token or on a photo or gradient.

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

  • Show who a piece of content belongs to: a comment author, an assignee, the members of a team.
  • Stand in for a missing or slow photo with one or two initials on a soft hue.

Khi nào không dùng

  • A logo, a product image or a picture in content. Use a native img.
  • A person picked as a value, such as a recipient in a field. Use Token with a leading avatar.
  • A status such as online or busy. Use Badge next to the name.
  • The only place a name appears in a list or comment. Write the name next to the avatar.

Biến thể

variant

soft: background-<hue> with text-<hue>, for lists and comment headers. solid: the <hue> solid with text-on-<hue>, inside a Token or on a photo or gradient where the soft fill would not stand out.

  • 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

The hue pair behind the initials. Never the accent. To keep one person's color across a page, pick the hue from something stable, such as their user id.

  • 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 for dense lists and table rows, md 32px for comment headers and member lists, lg 40px for profile headers.

  • 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ụ

Default

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

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

With photo

The initials show until the photo loads, and stay if it fails.

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

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

Next to a name

The name is written next to the avatar, so alt is empty and the avatar is hidden from screen readers.

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>

Without a name

An icon on the soft variant, for a guest or a deleted account.

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

<Avatar alt="Guest">
  <IconUser size={16} />
</Avatar>

Nên và không nên

Nên

  • Pass the person's name as alt, or alt="" when the name is written next to the avatar.
  • Always pass initials as children, even with src, so a slow or broken photo still shows something.
  • Use solid inside a Token or on a photo or gradient; use soft everywhere else.
  • Keep one hue per person across the page.

Không nên

  • Don't put an icon on a solid avatar; there is no icon token for a hue solid.
  • Don't use the accent or a status color as the fill.
  • Don't let the avatar replace a visible name in lists, comments or assignee fields.
  • Don't use it for logos or product images; use a native img.

Props

TênKiểuGiá trịMặc địnhMô tả
variantenumsoft | solidsoftsoft: background-<hue> with text-<hue>, for lists and comment headers. solid: the <hue> solid with text-on-<hue>, inside a Token or on a photo or gradient where the soft fill would not stand out.
colorenumgray | red | orange | yellow | green | teal | blue | purple | pinkgrayThe hue pair behind the initials. Never the accent. To keep one person's color across a page, pick the hue from something stable, such as their user id.
sizeenumsm | md | lgmdsm 24px for dense lists and table rows, md 32px for comment headers and member lists, lg 40px for profile headers.
srcstring--Photo URL. The initials show until it loads, and stay if it fails.
alt bắt buộcstring--Name of the person, team or workspace: Ada Lovelace. Pass an empty string when the name is written next to the avatar.

Slot

TênBắt buộcMô tả
fallbackcóOne or two initials, such as AL. On the soft variant, an icon for someone without a name.

Cấu tạo

PhầnMô tả
rootThe circle: radius-full, the hue fill, and the name of the avatar. 24, 32 or 40px.
imageThe photo, cropped to fill the circle. Rendered only once it has loaded, then it fades in with duration-medium (no fade under reduced motion).
fallbackThe children: one or two initials in medium weight, shown until the photo loads and when it fails or is missing.
iconOptional Tabler icon as the fallback on the soft variant, 12px in sm, 16px in md, 20px in lg.

Khả năng truy cập

Role: img

  • alt names the avatar on the root (role img with aria-label), so the name is the same whether the photo loads or the initials show, and the initials are never read out letter by letter. The type requires alt.
  • When the name is written next to the avatar, as in a comment header or a member list, pass alt="": the avatar is hidden from screen readers, so the name is not read twice.
  • Avatar is not interactive. To open a profile, put the avatar and the name inside one link, and name the link.
  • The hue is decoration. Never let it carry meaning such as a role or a status on its own.
  • Solid initials use text-on-<hue>, which meets 4.5:1 on every hue in both modes. There is no icon token for a hue solid, so an icon fallback is for the soft variant only.

Cài đặt

npx shadcn add https://werewolf-ui.vercel.app/r/avatar.json

Lệnh này thêm luôn styles/werewolf.css, bộ token mà mọi component dùng, và các component khác mà nó cần. Import file đó một lần trong CSS gốc, ngay sau @import "tailwindcss", với đường dẫn tính từ file CSS đó (từ app/globals.css là @import "../styles/werewolf.css").