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, and an optional name/email label group.
Installation
Install the component using the Tailgrids CLI.
npx @tailgrids/cli add avatarAnatomy
Import the component and pass the required props.
import { Avatar } from "@/registry/core/avatar";
export const AvatarExample = () => (
<Avatar
src="path/to/image.jpg"
alt="Profile picture of Random Person"
fallback="JD"
size="md"
status="online"
label={{
title: "Johurul Haque",
subtitle: "johurul@pimjo.com"
}}
/>
);Examples
Sizes
The Avatar component supports six predefined sizes: xs, sm, md, lg, xl, and xxl.
Status
Show predefined status indicator with none, online, offline, and busy.
Note:
The status indicator uses a white ring to visually separate it from the avatar's background.
Label
The label prop accepts an object with name and email to display descriptive text next to the avatar.
Avatar Group
Multiple avatars can be displayed in a group using the AvatarGroup component.
Note: The AvatarGroup component implements an overlapping effect using negative margin (-space-x-2) and adjusts the z-index of each avatar via inline styles to ensure the correct stacking order.
API Reference
Avatar
| Prop | Type | Default | Description |
|---|---|---|---|
size | 'xs', 'sm', 'md', 'lg', 'xl', 'xxl' | 'md' | Sets the size of the avatar |
src | string | - | Image URL. If not provided, the fallback is shown |
alt | string | - | Image alt text for accessibility |
fallback | string | - | Initials or short text shown when src is not provided Required. |
status | 'none', 'online', 'offline', 'busy' | 'none' | Displays a status indicator at the bottom-right corner |
label | { title: string, subtitle: string } | - | Optional object containing title and subtitle displayed next to the avatar |
className | string | - | Additional CSS classes to apply to the avatar |
AvatarGroup
| Prop | Type | Default | Description |
|---|---|---|---|
size | 'xs', 'sm', 'md' | 'md' | Sets the size of avatars in the group |
data | Array<{ src: string, alt: string }> | - | Array of avatar data objects to display |
className | string | - | Additional CSS classes to apply to the group container |
Accessibility
- Alt Text: The
altprop is used for the image, allowing screen readers to announce the avatar content. - Fallback: When no image is present, the fallback initials are visually clear and provide context.
- Semantic HTML: The component uses a
<figure>and<img>(or<span>for fallback) for semantic correctness.