Avatar

Installation#

npmpnpmyarnbun

npx sugarcoat add avatar

Examples#

Default#

Default

Sizes#

Available in five sizes to fit different UI contexts.

Sizes

Colors#

Avatars can use different color palettes for the fallback background.

Colors

Shapes#

Avatars support different shapes.

Shapes

Fallback#

The fallback is shown when the image fails to load or isn't provided.

Fallback

Shadow#

Add elevation with the shadow prop.

Shadow

Inactive State#

Show inactive or offline users with reduced opacity.

Inactive

Avatar Group#

Group multiple avatars together with optional overflow indicator.

Avatar Group

Avatar Group with Max#

Limit the number of visible avatars with overflow count.

Group with Max

User Card Example#

User Card

Anatomy#

<Avatar>
  <Avatar.Image src="..." alt="..." />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>
 
// Group
<Avatar.Group max={3}>
  <Avatar>...</Avatar>
  <Avatar>...</Avatar>
</Avatar.Group>

Usage#

Import

import { Avatar } from "@sugarcoat/ui-nxt";

Usage

<Avatar size="md" color="primary" shape="circle">
<Avatar.Image src="/path/to/image.jpg" alt="User Name" />
<Avatar.Fallback>UN</Avatar.Fallback>
</Avatar>

Props#

Avatar (Root)#

Prop	Type	Default	Description
size	"xs" \| "sm" \| "md" \| "lg" \| "xl"	"md"	Size of the avatar
color	"default" \| "neutral" \| "primary" \| "accent"	"default"	Color palette for the fallback background
shape	"square" \| "rounded" \| "circle"	"circle"	Shape of the avatar
shadow	boolean	true	Whether to show box shadow
inactive	boolean	false	Show avatar in inactive/offline state
css	SystemStyleObject	-	Additional CSS styles using Panda CSS syntax

Avatar.Image#

Prop	Type	Default	Description
srcrequired	string	-	URL of the avatar image
altrequired	string	-	Alternative text for the image

Avatar.Fallback#

Prop	Type	Default	Description
children	ReactNode	-	Content to display when image is unavailable (usually initials)

Avatar.Group#

Prop	Type	Default	Description
max	number	-	Maximum number of avatars to display before showing overflow count
size	"xs" \| "sm" \| "md" \| "lg" \| "xl"	-	Size for all avatars in the group
color	"default" \| "neutral" \| "primary" \| "accent"	-	Color for all avatars in the group
shape	"square" \| "rounded" \| "circle"	-	Shape for all avatars in the group

Accessibility#

Built on Base UI Avatar for robust accessibility
Always provide meaningful alt text for Avatar.Image
Fallback content is announced by screen readers when image fails
Use aria-label on Avatar.Group to describe the group context