Avatar & AvatarGroup

Enterprise-grade Avatar components for displaying user images, initials, or fallback icons, with support for statuses and grouped avatars.

---

Usage

Basic usage

import { Avatar, AvatarGroup } from "@nofinite/nui";

<Avatar src="/nofinite-logo.svg" alt="John Doe" />
<Avatar name="Samrat Kumar" />
<Avatar name="Samrat" status="online" />
<Avatar loading />
<Avatar fallbackIcon={<FaUser />} />

AvatarGroup usage

<AvatarGroup max={3}>
  <Avatar name="A" />
  <Avatar name="B" />
  <Avatar name="C" />
  <Avatar name="D" />
  <Avatar name="E" />
</AvatarGroup>

---

Variants

Avatar shapes

<Avatar shape="circle" />
<Avatar shape="rounded" />
<Avatar shape="square" />

Available shapes:

• circle – default circular avatar
• rounded – slightly rounded corners
• square – sharp square edges

Guidelines:

• Use circle for typical profile avatars.
• Use rounded for UI elements with a softer visual style.
• Use square for structured layouts or application icons.

---

Sizes

<Avatar size="sm" />
<Avatar size="md" />
<Avatar size="lg" />
<Avatar size="xl" />

Available sizes:

• sm – 28x28px
• md – 40x40px (default)
• lg – 56x56px
• xl – 72x72px

You can combine shape and size:

<Avatar size="lg" shape="rounded" />

---

States

<Avatar loading />
<Avatar status="online" />
<Avatar status="offline" />
<Avatar status="busy" />

• loading – displays a skeleton shimmer while the avatar is loading.
• status – displays a status indicator (online, offline, busy).
• Image error fallback – renders initials or fallbackIcon if the image fails to load.

---

Native Props / Composition

<Avatar
  aria-label="John Doe"
  data-testid="avatar-1"
  className="custom-class"
  onClick={() => console.log('clicked')}
>
  Content
</Avatar>

className and style can be applied to override or extend default styles.

---

Props

Avatar

Prop	Type	Default	Description
src	string	—	Image source URL
alt	string	—	Alternate text for the avatar image
name	string	—	User name, used for initials if image is missing
size	'sm' | 'md' | 'lg' | 'xl'	md	Avatar size
shape	'circle' | 'rounded' | 'square'	circle	Avatar shape
status	'online' | 'offline' | 'busy'	—	Optional status indicator
loading	boolean	false	Shows skeleton shimmer while loading
fallbackIcon	React.ReactNode	—	Icon shown if image and initials are missing
className	string	""	Additional CSS class
...rest	React.HTMLAttributes<HTMLElement>	—	Other native props

AvatarGroup

Prop	Type	Default	Description
children	React.ReactNode[]	—	Avatar components to group
max	number	3	Maximum avatars to show, overflow shown as +n
size	'sm' | 'md' | 'lg' | 'xl'	md	Size of avatars inside the group
className	string	""	Additional CSS class

---

Behavior Notes

• Avatars automatically fall back to initials or fallbackIcon if the image fails to load.
• AvatarGroup handles overflow by displaying +n for remaining avatars.
• The loading state disables image rendering and displays a skeleton shimmer.
• Status indicators are positioned at the bottom-right of the avatar.

---

Accessibility

• Avatar renders as a <div> by default with an accessible label derived from alt or name.
• Status indicators include an aria-label describing the current status.
• Supports keyboard focus when interactive via native props.
• Icon-only or fallback avatars include accessible labels.

<Avatar aria-label="John Doe" />

---

Layout

• Avatars render as inline-flex by default.
• AvatarGroup applies negative margins to achieve overlap.
• Full-width avatars can be achieved via style overrides:

<Avatar style={{ width: '100%' }} />

---

Best Practices

Do

• Use Avatar for user profiles, contact lists, and application icons.
• Use AvatarGroup to represent participants or team members.
• Always provide alt or name for accessibility and fallback behavior.

Don’t

• Do not place large or complex content inside avatars.
• Do not rely solely on images without providing a fallback.
• Do not communicate critical status information using color alone.