Avatar

React Avatar components are used to display user profile images, initials, or general fallback content. They are commonly used in user profiles, comment lists, team members, and account menus.

This Avatar component is built with React and styled using Tailwind CSS, giving developers control over size, layout, and presentation. It supports various sizes, user status indicators, an optional name/email label group, and overlapping avatar groups.

Installation

npx @tailgrids/cli add avatar

Anatomy

Import the component parts and combine them.

import {
  Avatar,
  AvatarImage,
  AvatarFallback,
  AvatarBadge
} from "@/components/tailgrids/core/avatar";

export const AvatarExample = () => (
  <Avatar size="md">
    <AvatarImage
      src="path/to/image.jpg"
      alt="Profile picture of Random Person"
    />
    <AvatarFallback>JD</AvatarFallback>
    <AvatarBadge status="online" />
  </Avatar>
);

Examples

Sizes

The Avatar component supports six predefined sizes: xs, sm, md, lg, xl, and xxl.

Status

Show predefined status indicator with online, offline, and busy on <AvatarBadge>. Omit the badge to render an avatar without a status indicator.

Note: The status indicator uses a white ring to visually separate it from the avatar's background.

Animated Status

Set ping on <AvatarBadge> to animate the status indicator.

Label

Wrap an <Avatar> with a name and subtitle inside a <figure> to associate the visual with descriptive text.

Avatar Group

Multiple avatars can be displayed in a group using the <AvatarGroup> component. Avatars overlap using negative margin and stack via a shared background ring.

Group with Count

Use <AvatarGroupCount> to display an overflow indicator for the group.

API Reference

Avatar

The root container for an avatar. Wraps an image, fallback, and optional badge.

AvatarImage

Renders the avatar's image. Falls back to AvatarFallback while loading or on error.

AvatarFallback

Rendered when the image is loading or has failed. Typically holds initials.

AvatarBadge

Displays a status indicator at the bottom-right corner of the avatar.

AvatarGroup

Wraps a collection of avatars with an overlapping layout.

AvatarGroupCount

Displays an overflow indicator (e.g. 5+) inside an <AvatarGroup>.

Accessibility

• Accessible name: Pass alt to <AvatarImage> to give the avatar a label. The label is announced separately from the status badge.
• Image alt text: When the avatar stands alone, give <AvatarImage> a descriptive alt. When it sits next to a text label (e.g. inside a <figure>/<figcaption>), pass alt="" so it's treated as decorative.
• Status indicator: The badge is announced as a separate role="img" with an aria-label of the current status (online / offline / busy). Color is reinforced with a shape glyph (a dash for offline, a minus for busy) so the indicator is not color-only. Pass live to make the badge announce status changes via aria-live="polite".
• Fallback: Initials are visually clear. When the image fails, you can pass aria-label to <AvatarFallback> to give the initials a name.
• Group semantics: <AvatarGroup> renders as role="group". Pass aria-label (e.g. "Team members") to describe the collection. <AvatarGroupCount> derives an aria-label of "${children} more" by default and accepts an explicit aria-label override.
• Semantic HTML: When pairing an avatar with a name/subtitle, wrap them in a <figure> with the text in a <figcaption>.