Fluxo UIFluxo UIv0.4.1

Avatar

A circular image-or-initials display with status indicators, plus a stacked group with overflow handling.

Basic Usage

Default Avatar

Image, initials, and icon fallbacks with optional status dot.

OnlineBusyAway
import { Avatar } from 'fluxo-ui';

<Avatar src="https://i.pravatar.cc/120?u=jane" alt="Jane Doe" />
<Avatar name="Jane Doe" />
<Avatar name="Marcus" status="online" />
<Avatar name="Anna" status="busy" shape="rounded" />

Sizes & Shapes

Sizes

Five preset sizes plus arbitrary pixel values.

Onlinexs
Onlinesm
Onlinemd
Onlinelg
Onlinexl
Online120px
<Avatar name="A" size="xs" />
<Avatar name="A" size="sm" />
<Avatar name="A" size="md" />
<Avatar name="A" size="lg" />
<Avatar name="A" size="xl" />
<Avatar name="A" size={120} />

Statuses

Statuses & Positions

All four statuses across all four positions.

onlineofflinebusyawaytop-left
Online
Offline
Busy
Away
top-right
Online
Offline
Busy
Away
bottom-left
Online
Offline
Busy
Away
bottom-right
Online
Offline
Busy
Away
<Avatar name="A" status="online" />
<Avatar name="B" status="busy" statusPosition="top-right" />
<Avatar name="C" status="away" statusPosition="bottom-left" />
<Avatar name="D" status="offline" statusPosition="top-left" />

Avatar Group

Avatar Group

Stack avatars with overflow and an optional popover listing the hidden ones (click +N). Hover any avatar to bring it to the front, click to fire the per-avatar callback.

Click an avatar (or one inside the +N popover) to see the callback fire.
OnlineBusy
const [selected, setSelected] = useState(null);

<AvatarGroup
  max={4}
  onAvatarClick={(item, index) => setSelected({ ...item, index })}
>
  <Avatar name="Jane Doe" status="online" />
  <Avatar name="Marcus Lopez" status="busy" />
  <Avatar name="Anna Kim" status="away" />
  <Avatar name="Olivia Park" status="offline" />
  <Avatar name="Diego Reyes" />
  <Avatar name="Hugo Liu" />
</AvatarGroup>

Clickable

Clickable Avatar

When onClick is provided the avatar renders as a focusable button.

Selected: —
<Avatar name="Jane" onClick={() => setSelected('Jane')} />

Import

import { Avatar, AvatarGroup } from 'fluxo-ui';
import type { AvatarProps, AvatarGroupProps, AvatarSize, AvatarShape, AvatarStatus } from 'fluxo-ui';

Avatar Props

src
string

Image URL

name
string

Used to derive initials and a deterministic background color when no src is provided or when the image fails

icon
IconComponent | ReactElement

Fallback when neither src nor name is available

alt
string

Accessible image alt text (defaults to name)

shape
'circle' | 'rounded' | 'square'"'circle'"

Avatar shape

size
'xs' | 'sm' | 'md' | 'lg' | 'xl' | number"'md'"

Preset size or pixel value

status
'online' | 'offline' | 'busy' | 'away'

Status indicator dot

statusPosition
'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'"'bottom-right'"

Status dot placement

colorFromName
boolean"true"

When no src, derive a stable background color from the name

loading
'lazy' | 'eager'"'lazy'"

Image loading strategy

onClick
(e: MouseEvent) => void

When provided, renders as a focusable button

id
string

HTML id attribute

className
string

Additional CSS classes

ariaLabel
string

Accessible label override

AvatarGroup Props

children
ReactNode

Multiple Avatar children

items
Array<AvatarProps>

Alternative array prop instead of children

max
number

Cap visible avatars; the rest collapse into a +N chip

overlap
number"8"

Pixels of overlap between adjacent avatars

direction
'ltr' | 'rtl'"'ltr'"

Visual stack order

size
'xs' | 'sm' | 'md' | 'lg' | 'xl' | number"'md'"

Applied to all children

shape
'circle' | 'rounded' | 'square'"'circle'"

Applied to all children

onAvatarClick
(item: AvatarProps, index: number, e: MouseEvent) => void

Fires when any avatar inside the group is clicked, including avatars revealed via the overflow popover. The index reflects the avatar's position in the original full list.

onOverflowClick
() => void

Custom handler for the +N chip; when omitted, opens a popover with the hidden avatars

id
string

HTML id attribute

className
string

Additional CSS classes

ariaLabel
string

Accessible label for the group

Features

Smart Fallbacks

Falls back from image → initials → icon when sources fail; deterministic color from the name.

4 Statuses

Online, busy, away, and offline with screen-reader-only labels.

Group with Overflow

Cap visible avatars; remaining ones collapse into a focusable +N popover.

Shape & Size

Circle / rounded / square shapes plus five preset sizes or arbitrary pixel values.