Avatar

Display user profile images with automatic fallback to initials when no image is available. Supports status indicators, size variants, and animated transitions.

Import

import { Avatar, AvatarGroup } from '@wavebooking/aqua-fusion';

Preview

Live PreviewOpen in Storybook

Loading preview...

Usage

<Avatar src="/user.jpg" alt="Jane Doe" name="Jane Doe" size="md" />

With status indicator

<Avatar
  src="/user.jpg"
  name="Jane Doe"
  status="online"
  showStatusIndicator
/>

Fallback initials

When src is not provided or the image fails to load, the component displays initials derived from the name prop.

<Avatar name="Jane Doe" size="lg" variant="primary" />

Avatar group

Stack multiple avatars with automatic overlap and a "+N" overflow indicator.

<AvatarGroup max={3} size="md">
  <Avatar name="Alice" src="/alice.jpg" />
  <Avatar name="Bob" src="/bob.jpg" />
  <Avatar name="Charlie" src="/charlie.jpg" />
  <Avatar name="Diana" src="/diana.jpg" />
</AvatarGroup>

Props

Avatar

Prop	Type	Default	Description
`src`	string \| null	-	Image URL for the avatar. Falls back to initials when absent or on error.
`alt`	string	-	Alt text for the image. Defaults to name or "Avatar".
`name`	string	-	User name used to generate fallback initials.
`size`	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	`'md'`	Size of the avatar.
`variant`	'default' \| 'primary' \| 'secondary'	`'default'`	Color variant for the fallback background.
`status`	'online' \| 'offline' \| 'busy' \| 'away'	-	Presence status for the indicator dot.
`showStatusIndicator`	boolean	`false`	Whether to display the status indicator dot.
`bordered`	boolean	`false`	Add a white ring and shadow around the avatar.
`animate`	boolean	`true`	Enable scale and hover animations via Framer Motion.
`className`	string	-	Additional CSS classes.

AvatarGroup

Prop	Type	Default	Description
`children`*	React.ReactNode	-	Avatar components to display in the group.
`max`	number	`4`	Maximum number of avatars to show before displaying the "+N" overflow.
`size`	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	`'md'`	Size applied to the overlap spacing.
`className`	string	-	Additional CSS classes for the group container.