Avatar
User identity representation with image, initials, icon, status indicators, shape variants, and grouping.
{ Avatar, AvatarGroup } from "@pepulux/ui"Image avatars
Pass src to show a photo. If the image fails to load, falls back to fallback initials then the generic user icon.
Letter avatars
Set fallback to show up-to-2 initials. Combine with bgColor and textColor for team color-coding.
Icon avatars
Pass an icon element via icon prop. Pair with bgColor for colored icon circles.
Sizes
Six sizes: xs (24px) through 2xl (64px).
Shape variants
circle (default), rounded (8px radius), or square.
Fallback chain
Broken src → fallback initials → generic user icon.
With status
status prop shows a badge: online (green), offline (gray), verified (blue), or count.
Upload avatar
Set onUpload to show a camera overlay on hover. Triggers your upload handler on click.
Avatar group
Stack avatars with AvatarGroup. max limits how many are shown; extras show as +N overflow.
Total avatars
total overrides the overflow count — useful when the full list comes from a server.
Custom surplus
renderSurplus customises the overflow bubble — e.g. abbreviating large numbers.
Spacing
spacing="medium" (default), "small", or a custom pixel value for the overlap.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | — | Image URL — falls back to initials if omitted or broken. |
| alt | string | — | Image alt text for accessibility. |
| fallback | string | — | Up-to-2 initials shown when no image. |
| icon | ReactNode | — | Icon element rendered instead of initials/user icon. |
| size | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "md" | Avatar diameter. |
| shape | "circle" | "rounded" | "square" | "circle" | Border radius variant. |
| bgColor | string | — | CSS color for letter/icon avatar background. |
| textColor | string | — | CSS color for initials or icon. Defaults to white when bgColor is set. |
| border | boolean | false | White ring border (used inside AvatarGroup). |
| status | "online" | "offline" | "verified" | "count" | — | Status badge position. |
| statusCount | number | — | Number shown in count badge. |
| onUpload | () => void | — | Shows camera overlay on hover — triggers this callback on click. |
AvatarGroup props
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| avatars* | AvatarGroupItem[] | — | List of avatar data objects. |
| max | number | 5 | Maximum avatars shown before overflow bubble. |
| total | number | — | Override the overflow count — useful for server-driven totals. |
| renderSurplus | (surplus: number) => ReactNode | — | Custom renderer for the overflow bubble. |
| size | "xs" | "sm" | "md" | "lg" | "sm" | Size applied to every avatar in the group. |
| spacing | "medium" | "small" | number | "medium" | Overlap amount: "medium" = 8px, "small" = 4px, or a custom pixel value. |