Avatar
Avatars represent a person or entity with an image or their initials.
Use the Avatar component to identify a user, team, or organization. It shows an image when src is provided and falls back to initials derived from alt.
Import
import { Avatar } from "@puzzle-ui/ui";Basic usage
Initials fallback
Without src, Avatar renders the initials of the alt text. Use this when a user has no picture or while an image is unavailable.
Size
Use size to set the width and height in pixels. The default is 32; smaller sizes are used as given.
Shape
Use shape to choose circle (default) or square.
With a badge
Wrap an Avatar in a Badge to show status or a count. Use anchorOverlap="circular" for circular avatars.
API reference
Avatar props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | — | Image URL. When omitted, initials are shown instead. |
alt | string | — | Accessible name; also the source of the initials fallback. |
size | number | 32 | Width and height in pixels. |
shape | "circle" | "square" | "circle" | Shape of the avatar. |
className | string | — | Additional CSS class names. |
Element props
Avatar accepts the remaining props of <img> (except width and height) and passes them to the rendered element, which is an <img> with src and a <span> otherwise.
TypeScript types
The component exports AvatarProps and AvatarShape.
Accessibility
- Always provide
alt. For images it is the alternative text; for the initials fallback it becomes thearia-labelof arole="img"element (the fallback is also shown when the image fails to load), and it is the source of the initials. - If the avatar sits next to the person's name and is purely decorative, pass
alt=""for the image variant so it is skipped by screen readers.