Avatar

PreviewCode

ALGH

Usage#

import { Avatar, AvatarFallback, AvatarImage } from "neelam-ui";
 
<Avatar>
  <AvatarImage src="/ada.jpg" alt="Ada Lovelace" />
  <AvatarFallback>AL</AvatarFallback>
</Avatar>

Mount AvatarImage unconditionally — even with a src you are not sure will resolve. It tracks its own load state and renders nothing when there is no src or the image failed, so the fallback handles every case and the browser's broken image can never show through.

Sizes#

size is "sm" (32px), "md" (40px, the default), or "lg" (48px). The box is a fixed height and width, which matters: the space is reserved before any image loads, so an avatar never causes a layout shift as it arrives.

The fallback delay#

delayMs on AvatarFallback holds it back briefly, so a fast-loading image does not flash initials before replacing them:

<AvatarFallback delayMs={600}>AL</AvatarFallback>

Omit it and the fallback renders immediately, which is the right default when images are slow or often missing.

alt is required#

AvatarImage's alt is a required prop, not an optional one. An avatar image conveys who it represents, so it needs a text alternative.

Keyboard#

Accessibility#

• The image carries a real alt, so it is announced or skipped according to what you pass.
• The fallback is text (initials or an icon), so it is announced normally — an avatar is never a silent empty circle.
• A fixed box means no layout shift as images resolve, which is a real usability issue for screen magnifier users, not only a Core Web Vitals number.
• Initials alone are ambiguous. Where identity matters, keep the name visible next to the avatar rather than relying on "AL" to carry it.

API reference#

Avatar#

AvatarImage#

AvatarFallback#