Skip to content
THE COMPONENT LIBRARY
Skip to content

Component reference

Avatar

People and teams with image and fallback identities.

Preview

Live preview

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

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.

Open preview

Shapes

circle, rounded and square.

Open preview

Image and states

The initials stay visible until the picture is ready; a broken image falls back to them.

Open preview

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
PimoluAvatarProps public API
NameTypeDefaultDescription
nameRequiredstring—Accessible name and source for initials.
srcstring | undefined—Image URL.
size"xs" | "sm" | "md" | "lg" | "xl" | undefined"md"Avatar size.
shape"circle" | "rounded" | "square" | undefined"circle"Avatar shape.
fallbackReactNode—Custom fallback instead of initials.
loading"eager" | "lazy" | undefined"lazy"Native image loading strategy.
onImageError(() => void) | undefined—Called when the image fails to load.
onChangeChangeEventHandler<HTMLSpanElement, Element> | undefined—Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefined—Standard React/HTML attribute.
classNamestring | undefined—Standard React/HTML attribute.
styleCSSProperties | undefined—Standard React/HTML attribute.
aria-labelstring | undefined—Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLSpanElement> | undefined—Standard React/HTML attribute.
nameRequired

string

No default extracted.

Accessible name and source for initials.

src

string | undefined

No default extracted.

Image URL.

size

"xs" | "sm" | "md" | "lg" | "xl" | undefined

Default: "md"

Avatar size.

shape

"circle" | "rounded" | "square" | undefined

Default: "circle"

Avatar shape.

fallback

ReactNode

No default extracted.

Custom fallback instead of initials.

loading

"eager" | "lazy" | undefined

Default: "lazy"

Native image loading strategy.

onImageError

(() => void) | undefined

No default extracted.

Called when the image fails to load.

onChange

ChangeEventHandler<HTMLSpanElement, Element> | undefined

No default extracted.

Standard React/HTML attribute.

defaultValue

string | number | readonly string[] | undefined

No default extracted.

Standard React/HTML attribute.

className

string | undefined

No default extracted.

Standard React/HTML attribute.

style

CSSProperties | undefined

No default extracted.

Standard React/HTML attribute.

aria-label

string | undefined

No default extracted.

Defines a string value that labels the current element.

onClick

MouseEventHandler<HTMLSpanElement> | undefined

No default extracted.

Standard React/HTML attribute.

PimoluAvatarGroupProps

Type source
PimoluAvatarGroupProps public API
NameTypeDefaultDescription
childrenReactNode—Direct Avatar children. Any other element is ignored: a fragment or a wrapper around the avatars is not supported.
maxnumber | undefined5Maximum 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.
onChangeChangeEventHandler<HTMLDivElement, Element> | undefined—Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefined—Standard React/HTML attribute.
classNamestring | undefined—Standard React/HTML attribute.
styleCSSProperties | undefined—Standard React/HTML attribute.
aria-labelstring | undefined—Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLDivElement> | undefined—Standard React/HTML attribute.
children

ReactNode

No default extracted.

Direct Avatar children. Any other element is ignored: a fragment or a wrapper around the avatars is not supported.

max

number | undefined

Default: 5

Maximum number of visible avatars.

size

"xs" | "sm" | "md" | "lg" | "xl" | undefined

Default: "md"

Size applied to every visible Avatar.

shape

"circle" | "rounded" | "square" | undefined

Default: "circle"

Shape applied to every visible Avatar.

spacing

"tight" | "normal" | "loose" | undefined

Default: "normal"

Controls how much avatars overlap.

getOverflowLabel

((hiddenCount: number) => string) | undefined

No default extracted.

Accessible label for the overflow counter.

onChange

ChangeEventHandler<HTMLDivElement, Element> | undefined

No default extracted.

Standard React/HTML attribute.

defaultValue

string | number | readonly string[] | undefined

No default extracted.

Standard React/HTML attribute.

className

string | undefined

No default extracted.

Standard React/HTML attribute.

style

CSSProperties | undefined

No default extracted.

Standard React/HTML attribute.

aria-label

string | undefined

No default extracted.

Defines a string value that labels the current element.

onClick

MouseEventHandler<HTMLDivElement> | undefined

No default extracted.

Standard React/HTML attribute.

Accessibility

  • Provide useful names when the avatar conveys identity; decorative portraits can have empty alternative text.
Read the accessibility guide →