Avatar
Avatar represents a person or entity with a photo, initials or an icon.
Always pass the real name. It is used for the initials, the colorful color and the screen reader label.
Import
Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.
TSX
// npm install yugen-uiimport { Avatar } from "yugen-ui";Variants
Each tile is a standalone example: hover to copy, or press Code to see the source.
Size
20, 24, 32 (default), 40, 48, 64, 96.
Color
neutral (default), brand, colorful (a stable color derived from a hash of name).
Presence
available, busy, away, offline.
Shape
circular for people; square for groups, apps and bots.
Image
src for a photo; an image that fails to load falls back to the initials; square for logos. image passes srcSet, sizes, loading… to the <img>, and renderImage uses a framework image component such as Next.js <Image>.
Usage
Do
- Use color="colorful" when several people appear side by side, so they are easier to tell apart.
- Use square for entities that aren't people.
Don't
- Don't pass an empty or made-up name.
- Don't set the avatar background color with className.
Props
| Prop · Type | Default | Description |
|---|---|---|
| namestring | Default: — | Required. Used for the initials, the color and the aria-label. |
| srcstring | Default: — | Profile image; falls back to the initials if it fails to load. |
| image{ srcSet, sizes, loading, decoding, crossOrigin, referrerPolicy, fetchPriority } | Default: — | Attributes for the <img>. The name stays on the role="img" wrapper. |
| renderImage(props) => ReactNode | Default: — | Renders the image with another component, e.g. (props) => <Image {...props} width={48} height={48} /> from Next.js. The initials still show when the image fails. |
| onLoadingStatusChange(status: "loading" | "loaded" | "error") => void | Default: — | Image load state, reported for each src. |
| fallbackDelaynumber | Default: 400 | Milliseconds to wait before showing the initials while the image loads. |
| size20 | 24 | 32 | 40 | 48 | 64 | 96 | Default: 32 | Size in px. |
| color"neutral" | "brand" | "colorful" | Default: "neutral" | Color palette. |
| shape"circular" | "square" | Default: "circular" | Shape. |
| presence"available" | "busy" | "away" | "offline" | Default: — | Status dot. |