Avatar
Avatar presents an image or fallback identity in a finished Brick frame.
Built from the published package
Know when Avatar is the right part
Use it when
Use it for people, organizations, or other compact identities in a fixed square frame with explicit fallback content.
Choose another path when
Do not use it as a generic image, upload control, avatar editor, group, or presence system. A status ring is visual metadata, not a live announcement. Use Image for a larger editorial or profile portrait when authored aspect ratio, crop, focal position, or available measure communicates identity.
Installation and imports
The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:
Add the modular stylesheet for every other Brick component the route renders.
Do not combine modular styles with styles.css or tokens.css.
Quick start
Visual recipes and states
Sizes change frame and fallback type together. Shape controls circle or rounded geometry. Status adds a non-interactive ring. Failed, absent, or delayed images resolve through Atom fallback behavior.
Examples
API
Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.
Public exports are Avatar, AvatarProps, AvatarSize, AvatarShape, and
AvatarStatus.
| Prop | Values | Default |
|---|---|---|
src | string | none |
alt | string (required; "" allowed) | — |
fallback | ReactNode (required) | — |
size | xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl | md |
shape | circle, rounded | circle |
status | online, away, busy, offline | none |
fallbackDelayMs | number | Atom default |
onLoadingStatusChange | Atom image-status callback | none |
Root span attributes except children and color are forwarded.
Accessibility
Use meaningful alt for an informative image. Use alt="" for decorative
identity; the fallback is then hidden from assistive technology. Without an
image, a non-empty alt labels the fallback image role. Status needs separate
accessible text when it conveys meaningful presence.
Nearby identity text does not make every Avatar decorative automatically.
Choose alt from context: preserve a meaningful alternative when the Avatar
adds identity that the surrounding content does not already provide, and use
alt="" only when the same identity is already supplied by adjacent text or
the owning control's accessible name.
Responsive behavior
Avatar stays at its selected size and does not choose breakpoints or responsive sources. Logical styling supports RTL; the application owns layout.
Styling and tokens
Customization
Use size, shape, and status first, then public Avatar tokens. Named 2xl–5xl
sizes cover larger square profile identities; use Image for non-square or
editorial portraits instead of overriding --brick-avatar-size. Root
className and style are escape hatches; image/fallback classes are styling
hooks, not renderable parts.
Tokens and CSS hooks
Stable hooks are .brick-avatar, .brick-avatar__image,
.brick-avatar__fallback, slots avatar, avatar-image, avatar-fallback,
and root data-size, data-shape, data-status. Public tokens are
--brick-avatar-size, --brick-avatar-radius, --brick-avatar-background,
--brick-avatar-foreground, --brick-avatar-outline-color,
--brick-avatar-outline-width,
--brick-avatar-status-ring-color, --brick-avatar-status-ring-width, and
--brick-avatar-status-ring-offset. The fallback-font variable is an internal
size-recipe detail, not a public token.
Advanced reference
Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.