Component reference
Avatar
People and teams with image and fallback identities.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Team
Members of the design system team.
Amélie Bernard
Product designer
Lucas Moreau
Front-end engineer
Sofia Rossi
Design engineer
Conversation
Author of the latest reply.
Amélie Bernard · 2 h ago
The initials stay readable until the picture finishes loading.
Project members
Five people, three visible, the rest counted.
Width adapts to the available space
"use client";
import {
Card,
CardHeader,
CardTitle,
CardDescription,
CardContent,
Avatar,
AvatarGroup
} from "@pimolu/react";
const members = [
{ name: "Amélie Bernard", role: "Product designer" },
{ name: "Lucas Moreau", role: "Front-end engineer" },
{ name: "Sofia Rossi", role: "Design engineer" },
];
const widerTeam = [
"Jean Dupont",
"Marie Laurent",
"Pimolu Developer",
"Nicolas Martin",
"Sophie Bernard",
];
export function DemoExample() {
return (
<div
className="grid grid-cols-[repeat(auto-fit,minmax(min(100%,280px),1fr))] gap-6 min-w-0 items-start"
>
<Card>
<CardHeader>
<CardTitle>Team</CardTitle>
<CardDescription>Members of the design system team.</CardDescription>
</CardHeader>
<CardContent>
<div className="grid gap-5 min-w-0">
{
members.map((member) => (<div
key={member.name}
className="flex flex-wrap items-center gap-3 min-w-0"
>
<Avatar name={member.name} size="sm" />
<div>
<p>{member.name}</p>
<p className="text-sm text-muted leading-relaxed">{member.role}</p>
</div>
</div>))
}
</div>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>Conversation</CardTitle>
<CardDescription>Author of the latest reply.</CardDescription>
</CardHeader>
<CardContent>
<div className="flex flex-wrap items-center gap-3 min-w-0">
<Avatar
name="Amélie Bernard"
src="/images/pimolu-avatar.svg"
size="sm"
/>
<div>
<p>
Amélie Bernard{" "}
<span className="text-sm text-muted leading-relaxed">· 2 h ago</span>
</p>
<p className="text-sm text-muted leading-relaxed">
The initials stay readable until the picture finishes loading.
</p>
</div>
</div>
</CardContent>
</Card>
<Card>
<CardHeader>
<CardTitle>Project members</CardTitle>
<CardDescription>Five people, three visible, the rest counted.</CardDescription>
</CardHeader>
<CardContent>
<AvatarGroup max={3} aria-label="Project members">
{widerTeam.map((name) => (<Avatar key={name} name={name} />))}
</AvatarGroup>
</CardContent>
</Card>
</div>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Sizes
xs, sm, md, lg and xl.
Shapes
circle, rounded and square.
Image and states
The initials stay visible until the picture is ready; a broken image falls back to them.
Usage
Use fallbacks for unavailable images and keep group overflow informative.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluAvatarProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
nameRequired | string | — | Accessible name and source for initials. |
src | string | undefined | — | Image URL. |
size | "xs" | "sm" | "md" | "lg" | "xl" | undefined | "md" | Avatar size. |
shape | "circle" | "rounded" | "square" | undefined | "circle" | Avatar shape. |
fallback | ReactNode | — | Custom fallback instead of initials. |
loading | "eager" | "lazy" | undefined | "lazy" | Native image loading strategy. |
onImageError | (() => void) | undefined | — | Called when the image fails to load. |
onChange | ChangeEventHandler<HTMLSpanElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLSpanElement> | undefined | — | Standard React/HTML attribute. |
nameRequiredstringNo default extracted.
Accessible name and source for initials.
srcstring | undefinedNo default extracted.
Image URL.
size"xs" | "sm" | "md" | "lg" | "xl" | undefinedDefault: "md"
Avatar size.
shape"circle" | "rounded" | "square" | undefinedDefault: "circle"
Avatar shape.
fallbackReactNodeNo default extracted.
Custom fallback instead of initials.
loading"eager" | "lazy" | undefinedDefault: "lazy"
Native image loading strategy.
onImageError(() => void) | undefinedNo default extracted.
Called when the image fails to load.
onChangeChangeEventHandler<HTMLSpanElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLSpanElement> | undefinedNo default extracted.
Standard React/HTML attribute.
PimoluAvatarGroupProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Direct Avatar children. Any other element is ignored: a fragment or a wrapper around the avatars is not supported. |
max | number | undefined | 5 | Maximum number of visible avatars. |
size | "xs" | "sm" | "md" | "lg" | "xl" | undefined | "md" | Size applied to every visible Avatar. |
shape | "circle" | "rounded" | "square" | undefined | "circle" | Shape applied to every visible Avatar. |
spacing | "tight" | "normal" | "loose" | undefined | "normal" | Controls how much avatars overlap. |
getOverflowLabel | ((hiddenCount: number) => string) | undefined | — | Accessible label for the overflow counter. |
onChange | ChangeEventHandler<HTMLDivElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | Standard React/HTML attribute. |
childrenReactNodeNo default extracted.
Direct Avatar children. Any other element is ignored: a fragment or a wrapper around the avatars is not supported.
maxnumber | undefinedDefault: 5
Maximum number of visible avatars.
size"xs" | "sm" | "md" | "lg" | "xl" | undefinedDefault: "md"
Size applied to every visible Avatar.
shape"circle" | "rounded" | "square" | undefinedDefault: "circle"
Shape applied to every visible Avatar.
spacing"tight" | "normal" | "loose" | undefinedDefault: "normal"
Controls how much avatars overlap.
getOverflowLabel((hiddenCount: number) => string) | undefinedNo default extracted.
Accessible label for the overflow counter.
onChangeChangeEventHandler<HTMLDivElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLDivElement> | undefinedNo default extracted.
Standard React/HTML attribute.
Accessibility
- Provide useful names when the avatar conveys identity; decorative portraits can have empty alternative text.