avatar

Image avatar with automatic image-load tracking and fallback.

Renders an avatar image, falling back to a provided element (initials, icon) when the image fails to load or is still loading.

Installation

pnpm add @fluixi-ui/avatar

Usage

import { Avatar, AvatarImage, AvatarFallback } from '@fluixi-ui/avatar';

<Avatar>
  <AvatarImage src="/user.jpg" alt="Jane Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Parts

Part	Description
`Avatar`	Root container.
`AvatarImage`	The `<img>` element. Tracks load status and notifies via `onLoadingStatusChange`.
`AvatarFallback`	Shown while the image is loading or has errored; `delayMs` delays its appearance to avoid flashing on fast loads.
`AvatarIndicator`	A status dot, count or icon on the avatar's edge. See Indicator.

AvatarFallback exposes data-status (idle | loading | loaded | error) on AvatarImage so the skin can animate the transition.

Indicator

AvatarIndicator puts a status dot, a count or an icon on the edge of an avatar. Place it inside the Avatar.

import { Avatar, AvatarImage, AvatarFallback, AvatarIndicator } from '@fluixi-ui/avatar';

<Avatar>
  <AvatarImage src="/user.jpg" alt="Jane Doe" />
  <AvatarFallback>JD</AvatarFallback>
  <AvatarIndicator label="Online" />
</Avatar>

<Avatar>
  <AvatarFallback>JD</AvatarFallback>
  <AvatarIndicator placement="top-end" tone="danger" label="3 unread">3</AvatarIndicator>
</Avatar>

Prop	Default	Description
`placement`	`bottom-end`	A corner (`top-start`, `top-end`, `bottom-start`, `bottom-end`) or the middle of an edge (`top`, `end`, `bottom`, `start`). `start` and `end` follow the text direction. The list is exported as `AVATAR_INDICATOR_PLACEMENTS`.
`overlap`	`circular`	`circular` puts a corner indicator on the circle, 45 degrees round from the edge; `rectangular` on the box corner, for a square avatar.
`tone`	`success`	`neutral`, `primary`, `info`, `success`, `warning` or `danger`.
`label`		What the indicator means, announced to assistive technology. Without it the indicator is hidden from it.
`children`		A count or an icon. Without children the indicator is a dot.

A ring in the page colour cuts the indicator out of the avatar; set --flx-ui-avatar-indicator-ring when the avatar sits on another surface. The size comes from the avatar (a quarter of it for a dot) and can be set with --flx-ui-avatar-indicator-dot and --flx-ui-avatar-indicator-size.

Avatar group

Cluster overlapping avatars with AvatarGroup, and cap the list with a trailing +N chip via AvatarGroupOverflow. Overflow is a display concern, slice the avatars you render yourself.

import { Avatar, AvatarImage, AvatarFallback, AvatarGroup, AvatarGroupOverflow } from '@fluixi-ui/avatar';

<AvatarGroup>
  <Avatar><AvatarImage src="/a.jpg" /><AvatarFallback>A</AvatarFallback></Avatar>
  <Avatar><AvatarImage src="/b.jpg" /><AvatarFallback>B</AvatarFallback></Avatar>
  <AvatarGroupOverflow>+4</AvatarGroupOverflow>
</AvatarGroup>

Part	Description
`AvatarGroup`	Overlapping cluster. `spacing` (px, default `8`) sets how far each avatar tucks under the previous.
`AvatarGroupOverflow`	Trailing `+N` chip, styled like an avatar.

Part of the Fluixi UI component library. Made with ☕ by the Fluixi team.