Avatar
Stable person identities, organization plates, and compact people groups.
Installation
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"Import @commenda/pathfinder/styles.css once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from @commenda/pathfinder/avatar. Interactive callbacks belong in a client component in Next.js App Router.
API reference
| Prop | Type | Behavior |
|---|---|---|
identityRequired | AvatarIdentityView fields · 3 shapes | Required discriminated person, organization, or logo object |
size | AvatarSize | 24 |
label | string | Optional accessible-name override/localized fallback |
decorative | boolean | false; true suppresses name and tooltip |
tooltipConfig | false | ObjectView fields | Name tooltip enabled; false when visible copy already names it |
className | string | Additional classes for the component root. |
id | string | Stable HTML identifier for the component. |
identityObject fields
Choose one of these 3 shapes. Do not combine fields excluded by the selected shape.
Option 1
| Field | Type | Requirement |
|---|---|---|
kind | "person" | Required |
userId | string | Optional |
name | string | Optional |
email | string | Optional |
src | string | Optional |
Option 2
| Field | Type | Requirement |
|---|---|---|
kind | "organization" | Required |
name | string | Required |
src | string | Optional |
Option 3
| Field | Type | Requirement |
|---|---|---|
kind | "logo" | Required |
label | string | Required |
artwork | ReactElement<any, string | React.JSXElementConstructor<any>> | Required |
tooltipConfigObject fields
| Field | Type | Requirement |
|---|---|---|
label | string | Optional |
Root IDs, className, appropriate ARIA attributes, and typed refs are supported.
Usage rules
Identity structure
type AvatarIdentity =
| {
kind: 'person';
userId?: string;
name?: string;
email?: string;
src?: string;
}
| { kind: 'organization'; name: string; src?: string }
| { kind: 'logo'; label: string; artwork: ReactElement };Person: photo → initials → neutral person icon. Initials use name, then email local-part; grapheme-aware extraction preserves emoji and non-Latin names. Size 16 shows one initial; other sizes show up to two. Image failure keeps the same dimensions and reveals the fallback.
Tone comes from the stable user ID, never name/email. UTF-8 FNV-1a modulo eight chooses clay, apricot, ochre, olive, sage, dusk, plum, or rose using existing token pairs. Without an ID the fallback is neutral. The accessible fallback is “Unknown person”; label can localize it. Organizations use a neutral plate, logos use supplied artwork, legal entities use flags. Commenda's existing short-form mark is Icons.Interface.CommendaBrand.
AvatarGroup
| Prop | Type | Default / behavior |
|---|---|---|
| label | string | Required group name |
| people | readonly { id; name?; email?; src? }[] | Stable id also determines tone |
| size | 20 or 24 or 32 | 24 |
| surface | white or canvas | white; determines separating ring |
| overflowConfig | { label?(count): string; formatNames?(names): string } | Localize disclosure and name list |
| unknownLabel | string | Unknown person |
Three visible people, then +N. Names remain available on hover/focus, and the overflow supports tap. Escape or clicking outside closes the disclosure. Earlier people sit above later ones with a 1.5px surface ring. Empty groups render no fake members; hidden people must be supplied, not just a total count. Use a full people list elsewhere for very large groups.
Examples
Sizes
Types
Groups
Fallback
Photo
An image loads inside the same fixed-size frame, retaining initials if loading fails. The demo portrait is a local copy of the sample provided in Figma (identified there as an Unsplash free-license image). Replace the example URL with your application's image URL.
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Avatar and AvatarGroup
Source: 412:74, group 412:12893, palette 533:26418, docs 414:485.
AVATAR-01— Source: people circular; organization/logo rounded plate, radii5/6/8/10/12/20 for sizes16/20/24/32/40/64. Legal entities use flags. Identity is a person/organization/logo union. Reuse the existing CommendaBrand icon for the short-form mark.AVATAR-02— Source/Pathfinder: stable user-ID FNV-1a modulo8; UTF-8 and unsigned32 arithmetic. Tone order clay/apricot/ochre/olive/sage/dusk/plum/rose; reuse token pairs. No random tone or name/email hash. Missing user ID is neutral.AVATAR-03— Source/Pathfinder: photo, then name/email initials, then neutral person. Grapheme-safe uppercase initials, one at16 and up to two otherwise. Dimensions stay reserved on image failure. Logo slots are10/12/14/18/22/36 at the six sizes, on white; neutral-person artwork is12/12/16/16/20/33.6. Full accessible name or localized fallback; decorative avatars suppress tooltip and repeated naming.AVATAR-04— Source: show three people then +N; tooltip names hidden people; group sizes20/24/32. Earlier people stack above later ones. 1.5 surface-color rings separate overlapping avatars. Do not supply count without identities.AVATAR-05— Pathfinder: names reachable on focus; overflow supports touch tap, outside press, and Escape. Localize overflow label/name list and unknown identity copy. No action semantics on ordinary avatars. Large groups need a full people list in the owning interface.