Avatar

An operator identity chip — image with automatic initials fallback and optional status pip — plus AvatarStack for overlapping crew rosters.

Import

import { Avatar, AvatarStack } from "@roger-emerson/ploxum-primitives";

Usage

{/* Shift lead with presence */}
<div className="flex items-center gap-2">
  <Avatar name="Dana Okafor" src="/crew/dana.jpg" status="live" />
  <span className="text-[13px]">Dana Okafor — Show Caller</span>
</div>
 
{/* On-shift security crew, collapsed past 4 */}
<AvatarStack
  max={4}
  people={[
    { name: "Dana Okafor", src: "/crew/dana.jpg" },
    { name: "Marcus Reid" },
    { name: "Priya Shah", src: "/crew/priya.jpg" },
    { name: "Tom Alvarez" },
    { name: "Lena Fischer" },
    { name: "Omar Haddad" },
  ]}
  size="sm"
/>

Props

Avatar

Prop	Type	Default	Description
`name`	`string`	—	Operator name; used for the initials fallback and as the accessible label. Required.
`src`	`string`	—	Image URL. On load error the initials fallback renders automatically.
`colorFromName`	`boolean`	`false`	Derive the initials-fallback tint from a hash of `name` (a stable, on-brand palette tone), so each operator gets a consistent colour. No effect once an image loads.
`size`	`"xs" \| "sm" \| "md" \| "lg"`	`"md"`	20 / 24 / 32 / 40 px.
`status`	`StatusPipStatus`	—	`"live" \| "ok" \| "warning" \| "critical" \| "offline" \| "unknown"` — renders a `StatusPip` anchored bottom-right.
`className`	`string`	—	Merged onto the root `<span>`.
`ref`	`Ref<HTMLSpanElement>`	—	Ref to the root `<span>`.

Also accepts all HTMLAttributes<HTMLSpanElement> except children. The root carries role="img" labelled with name.

AvatarStack

Prop	Type	Default	Description
`people`	`Pick<AvatarProps, "name" \| "src">[]`	—	Roster, in display order. Required.
`max`	`number`	`4`	Maximum avatars shown before collapsing into a `+N` chip.
`size`	`"xs" \| "sm" \| "md" \| "lg"`	`"md"`	Applied to every avatar and the overflow chip.
`className`	`string`	—	Merged onto the root.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the root.

Design rules

Presence is conveyed by StatusPip — shape + color, never hue alone. Don't replace the pip with a colored ring.
Image failures fall back to initials automatically; don't pre-validate URLs or render your own fallback branch.
colorFromName keys the fallback tint off a hash of name, drawn from the on-brand token palette — same person, same colour, every render. Don't hand-pick per-avatar colours to fake this; let the hash do it so a roster stays distinguishable without going off-brand.
Stack entries are keyed by name — names within one people array must be unique.
The overflow chip and initials use tabular numerals / the elevated surface tone; don't restyle them per-theme — they derive from tokens.

Storybook

Open Avatar in Storybook ↗