Avatar
An image element with a fallback for representing the user.
Overview
The Avatar component displays user profile images with automatic fallback to initials or custom content when images fail to load, providing consistent user representation across your application.
The AvatarGroup wrapper arranges multiple avatars in an overlapping stack with optional integrated tooltips. It uses a CSS mask to cut a clean negative-space gap between adjacent avatars, so it stays bg-color independent on any surface.
Usage
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupTooltip,
AvatarImage,
} from "@tilt-legal/cubitt-components/primitives";<Avatar>
<AvatarImage src={imageUrl} alt="User name" />
<AvatarFallback>IW</AvatarFallback>
</Avatar>Examples
Basic
import { Avatar, AvatarFallback, AvatarImage } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/cooper-corbett.webp"
alt="Cooper Corbett"
/>
<AvatarFallback>CC</AvatarFallback>
</Avatar>
);
}Fallback
Display fallback content when the image fails to load or is not available.
import { Avatar, AvatarFallback } from "@tilt-legal/cubitt-components/primitives";
import { User } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Component() {
return (
<div className="flex gap-6">
<Avatar>
<AvatarFallback>IW</AvatarFallback>
</Avatar>
<Avatar>
<AvatarFallback>
<User className="size-4" />
</AvatarFallback>
</Avatar>
</div>
);
}With Indicator
Add indicators such as verification badges to avatars.
import {
Avatar,
AvatarFallback,
AvatarImage,
AvatarIndicator,
} from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
<Avatar className="size-14">
<AvatarImage
src="https://tilt.legal/images/about/avatars/isaac-wong.webp"
alt="Isaac Wong"
/>
<AvatarFallback>IW</AvatarFallback>
<AvatarIndicator className="-end-1 -top-1">
<svg viewBox="0 0 15 16" className="h-4 fill-brand-1">
<path d="…" />
</svg>
</AvatarIndicator>
</Avatar>
);
}With Status
Display user online/offline status using the AvatarStatus component.
import {
Avatar,
AvatarFallback,
AvatarImage,
AvatarIndicator,
AvatarStatus,
} from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/isaac-wong.webp"
alt="Isaac Wong"
/>
<AvatarFallback>IW</AvatarFallback>
<AvatarIndicator className="-end-1.5 -top-1.5">
<AvatarStatus variant="online" className="size-2.5" />
</AvatarIndicator>
</Avatar>
);
}With Badge
Combine avatars with badges to show notification counts or other indicators.
import {
Avatar,
AvatarFallback,
AvatarImage,
AvatarIndicator,
Badge,
} from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/cooper-corbett.webp"
alt="Cooper Corbett"
/>
<AvatarFallback>CC</AvatarFallback>
<AvatarIndicator className="-end-2 -top-2">
<Badge
variant="info"
size="xs"
className="border border-background"
>
6
</Badge>
</AvatarIndicator>
</Avatar>
);
}Sizes
Avatars can be sized using Tailwind's sizing utilities.
import { Avatar, AvatarFallback, AvatarImage } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
<div className="flex flex-wrap items-center gap-6">
<Avatar className="size-6">…</Avatar>
<Avatar className="size-8">…</Avatar>
<Avatar className="size-10">…</Avatar>
<Avatar className="size-14">…</Avatar>
<Avatar className="size-20">…</Avatar>
</div>
);
}Group
Wrap avatars in AvatarGroup to display them as an overlapping stack. Add a trailing avatar with a count fallback to indicate additional users.
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarImage,
} from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
<AvatarGroup>
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/isaac-wong.webp"
alt="Isaac Wong"
/>
<AvatarFallback>IW</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/cooper-corbett.webp"
alt="Cooper Corbett"
/>
<AvatarFallback>CC</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/sandon-lai.webp"
alt="Sandon Lai"
/>
<AvatarFallback>SL</AvatarFallback>
</Avatar>
<Avatar>
<AvatarFallback>+5</AvatarFallback>
</Avatar>
</AvatarGroup>
);
}Group With Tooltip
Each Avatar can include an AvatarGroupTooltip child to render content on hover.
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupTooltip,
AvatarImage,
} from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
<AvatarGroup>
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/isaac-wong.webp"
alt="Isaac Wong"
/>
<AvatarFallback>IW</AvatarFallback>
<AvatarGroupTooltip>
<p>Isaac Wong</p>
</AvatarGroupTooltip>
</Avatar>
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/cooper-corbett.webp"
alt="Cooper Corbett"
/>
<AvatarFallback>CC</AvatarFallback>
<AvatarGroupTooltip>
<p>Cooper Corbett</p>
</AvatarGroupTooltip>
</Avatar>
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/sandon-lai.webp"
alt="Sandon Lai"
/>
<AvatarFallback>SL</AvatarFallback>
<AvatarGroupTooltip>
<p>Sandon Lai</p>
</AvatarGroupTooltip>
</Avatar>
<Avatar>
<AvatarFallback>+5</AvatarFallback>
<AvatarGroupTooltip>
<p>5 more users</p>
</AvatarGroupTooltip>
</Avatar>
</AvatarGroup>
);
}Group Inverted Overlap
Set invertOverlap to flip stack direction so the leftmost avatar sits on top.
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupTooltip,
AvatarImage,
} from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
<AvatarGroup invertOverlap>
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/isaac-wong.webp"
alt="Isaac Wong"
/>
<AvatarFallback>IW</AvatarFallback>
<AvatarGroupTooltip>
<p>Isaac Wong</p>
</AvatarGroupTooltip>
</Avatar>
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/cooper-corbett.webp"
alt="Cooper Corbett"
/>
<AvatarFallback>CC</AvatarFallback>
<AvatarGroupTooltip>
<p>Cooper Corbett</p>
</AvatarGroupTooltip>
</Avatar>
<Avatar>
<AvatarImage
src="https://tilt.legal/images/about/avatars/sandon-lai.webp"
alt="Sandon Lai"
/>
<AvatarFallback>SL</AvatarFallback>
<AvatarGroupTooltip>
<p>Sandon Lai</p>
</AvatarGroupTooltip>
</Avatar>
<Avatar>
<AvatarFallback>+2</AvatarFallback>
<AvatarGroupTooltip>
<p>2 more users</p>
</AvatarGroupTooltip>
</Avatar>
</AvatarGroup>
);
}API Reference
Avatar
The root container for the avatar component.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | Additional CSS classes |
...props | React.ComponentProps<typeof Avatar> | - | All other avatar root props |
AvatarImage
Displays the user's profile image.
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | - | Image source URL |
alt | string | - | Alternative text for the image |
className | string | - | Additional CSS classes |
...props | React.ComponentProps<typeof AvatarImage> | - | All other avatar image props |
AvatarFallback
Content to display when the image fails to load or is unavailable.
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | - | Fallback content (usually initials or icon) |
className | string | - | Additional CSS classes |
...props | React.ComponentProps<typeof AvatarFallback> | - | All other avatar fallback props |
AvatarIndicator
Container for indicators like status badges or notification counts.
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | - | Indicator content |
className | string | - | Additional CSS classes for positioning |
...props | React.HTMLAttributes<HTMLDivElement> | - | All other div HTML attributes |
AvatarStatus
Displays a status indicator (online, offline, busy, away).
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "online" | "offline" | "busy" | "away" | "online" | Status variant |
className | string | - | Additional CSS classes |
...props | React.HTMLAttributes<HTMLDivElement> | - | All other div HTML attributes |
AvatarGroup
Wraps multiple Avatar components in an overlapping stack with mask-based separation. Avatars render directly unless they include AvatarGroupTooltip, in which case the avatar container becomes the tooltip trigger.
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactElement[] | - | Array of Avatar components to render in the group |
invertOverlap | boolean | false | Inverts the overlap direction of avatars |
size | string | number | 43 | Size of each avatar in pixels |
border | string | number | 3 | Border width used to compute the mask cutout (px) |
columnSize | string | number | 37 | Width of each avatar column (px) — controls overlap |
align | "start" | "center" | "end" | "end" | Vertical alignment of avatars |
className | string | - | Additional CSS classes to apply to the group |
...props | React.ComponentProps<"div"> | - | All other div HTML attributes |
AvatarGroupTooltip
Renders tooltip content shown on hover for a group avatar. Add it as a child of an Avatar inside AvatarGroup.
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | - | Content to display in the tooltip |
side | TooltipContentProps["side"] | "top" | Preferred tooltip side |
sideOffset | TooltipContentProps["sideOffset"] | 12 | Distance between the avatar and tooltip |
className | string | - | Additional CSS classes to apply to the tooltip |
...props | React.ComponentProps<typeof TooltipContent> | - | All other tooltip content props |