Avatar
User identity representation with image, initials, icon, status indicators, shape variants, and grouping.
{ Avatar, AvatarGroup, AvatarLabelGroup } 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
Seven sizes: xs (24px), sm (32px), md (40px), lg (48px), xl (56px), 2xl (64px), 3xl (96px).
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 tick), company (logo image), or count.
PBLS3Avatar label group
Avatar with a name and supporting text. Sizes sm, md, lg and xl follow Figma's text scale.
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.
Group sizes and add button
Figma sizes xs, sm and md overlap by 4, 8 and 12px. addButton shows the dashed + button.
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" | "3xl" | "md" | Avatar diameter: 24 / 32 / 40 / 48 / 56 / 64 / 96px. |
| 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" | "company" | "count" | — | Corner status badge. |
| companyLogo | string | — | Logo image URL shown when status="company". |
| 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 | — | Overlap amount. Defaults to the Figma overlap for the size (xs 4px, sm 8px, md 12px); "medium" = 8px, "small" = 4px, or a custom pixel value. |
| addButton | boolean | false | Shows the dashed + button after the avatars. |
| onAdd | () => void | — | Called when the + button is clicked. |