Hudoro Avatar

@hudoro/avatar is a React avatar component package for user photos, initials, loading placeholders, status badges, and grouped avatars.

Installation

pnpm add @hudoro/avatar

This package expects:

• react >=18.0.0 <20.0.0
• react-dom >=18.0.0 <20.0.0

Features

• Preset sizes: xs, sm, md, lg
• Custom sizes: 40, "40px", "3rem"
• Shapes: circle, rounded, square
• Image fallback to initials or custom fallback icon
• Optional status badge: online, offline, busy, away
• Explicit loading state with skeleton via isLoading
• AvatarGroup with overlap and +N overflow

Basic Usage

import {Avatar, AvatarGroup} from "@hudoro/avatar";

export function Example() {
  return (
    <>
      <Avatar
        src="/user.png"
        alt="Jane Doe"
        size="lg"
        status="online"
      />

      <Avatar
        name="John Doe"
        size={48}
        shape="rounded"
        backgroundColor="#dbeafe"
      />

      <AvatarGroup
        size="md"
        max={3}
        avatars={[
          {src: "/a.png", alt: "User A"},
          {src: "/b.png", alt: "User B"},
          {name: "User C"},
          {name: "User D"},
        ]}
      />
    </>
  );
}

Avatar Props

| Prop | Type | Notes | | :--- | :--- | :--- | | src | string | Image source. | | alt | string | Accessible image label. | | size | "xs" \| "sm" \| "md" \| "lg" \| number \| string | Supports presets and custom values. | | sizes | same as size | Deprecated. Use size. | | shape | "circle" \| "rounded" \| "square" | Defaults to circle. | | name | string | Used to build fallback initials. | | initials | string | Overrides generated initials. | | fallbackIcon | ReactNode | Rendered when image is missing or fails. | | status | "online" \| "offline" \| "busy" \| "away" | Shows a badge in the corner. | | isLoading | boolean | Shows skeleton. Loading is not automatic. | | bordered | boolean | Defaults to true. | | borderColor | string | Custom border color. | | backgroundColor | string | Background color for fallback state. | | objectFit | CSS object-fit value | Defaults to cover. | | onError | image event handler | Called when image loading fails. |

All other standard img props are supported except native sizes, because that name is used for backward compatibility with the old avatar API.

AvatarGroup Props

| Prop | Type | Notes | | :--- | :--- | :--- | | avatars | AvatarProps[] | Required list of avatars. | | max | number | Maximum visible avatars before +N. | | overlap | number \| string | Overlap spacing between items. | | size | AvatarSize | Default size for group items. | | shape | AvatarShape | Default shape for group items. | | bordered | boolean | Default border behavior for group items. | | borderColor | string | Shared border color. | | backgroundColor | string | Shared fallback background. |

Notes

• If src is empty or the image fails to load, the component falls back to initials or fallbackIcon.
• isLoading must be passed explicitly when you want to show the skeleton.
• For local development examples, run pnpm dev.
• To validate the package output, run pnpm build.