## Overview [#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 [#usage]
```tsx showLineNumbers
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupTooltip,
AvatarImage,
} from "@tilt-legal/cubitt-components/avatar";
```
```tsx showLineNumbers
IW
```
***
## Examples [#examples]
### Basic [#basic]
```tsx
import {
Avatar,
AvatarFallback,
AvatarImage,
} from "@tilt-legal/cubitt-components/avatar";
export default function Component() {
return (
CC
);
}
```
### Fallback [#fallback]
Display fallback content when the image fails to load or is not available.
```tsx
import {
Avatar,
AvatarFallback,
} from "@tilt-legal/cubitt-components/avatar";
import { User } from "@tilt-legal/cubitt-icons/ui/outline";
export default function Component() {
return (
IW
);
}
```
### With Indicator [#with-indicator]
Add indicators such as verification badges to avatars.
```tsx
import {
Avatar,
AvatarFallback,
AvatarImage,
AvatarIndicator,
} from "@tilt-legal/cubitt-components/avatar";
export default function Component() {
return (
IW
);
}
```
### With Status [#with-status]
Display user online/offline status using the `AvatarStatus` component.
```tsx
import {
Avatar,
AvatarFallback,
AvatarImage,
AvatarIndicator,
AvatarStatus,
} from "@tilt-legal/cubitt-components/avatar";
export default function Component() {
return (
IW
);
}
```
### With Badge [#with-badge]
Combine avatars with badges to show notification counts or other indicators.
```tsx
import {
Avatar,
AvatarFallback,
AvatarImage,
AvatarIndicator,
} from "@tilt-legal/cubitt-components/avatar";
import { Badge } from "@tilt-legal/cubitt-components/badge";
export default function Component() {
return (
CC
6
);
}
```
### Sizes [#sizes]
Avatars can be sized using Tailwind's sizing utilities.
```tsx
import {
Avatar,
AvatarFallback,
AvatarImage,
} from "@tilt-legal/cubitt-components/avatar";
export default function Component() {
return (
……………
);
}
```
### Group [#group]
Wrap avatars in `AvatarGroup` to display them as an overlapping stack. Add a trailing avatar with a count fallback to indicate additional users.
```tsx
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarImage,
} from "@tilt-legal/cubitt-components/avatar";
export default function Component() {
return (
IWCCSL+5
);
}
```
### Group With Tooltip [#group-with-tooltip]
Each `Avatar` can include an `AvatarGroupTooltip` child to render content on hover.
```tsx
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupTooltip,
AvatarImage,
} from "@tilt-legal/cubitt-components/avatar";
export default function Component() {
return (
IW
Isaac Wong
CC
Cooper Corbett
SL
Sandon Lai
+5
5 more users
);
}
```
### Group Inverted Overlap [#group-inverted-overlap]
Set `invertOverlap` to flip stack direction so the leftmost avatar sits on top.
```tsx
import {
Avatar,
AvatarFallback,
AvatarGroup,
AvatarGroupTooltip,
AvatarImage,
} from "@tilt-legal/cubitt-components/avatar";
export default function Component() {
return (
IW
Isaac Wong
CC
Cooper Corbett
SL
Sandon Lai
+2
2 more users
);
}
```
***
## API Reference [#api-reference]
### Avatar [#avatar]
The root container for the avatar component.
| Prop | Type | Default | Description |
| ----------- | ------------------------------------- | ------- | --------------------------- |
| `className` | `string` | - | Additional CSS classes |
| `...props` | `React.ComponentProps` | - | All other avatar root props |
### AvatarImage [#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` | - | All other avatar image props |
### AvatarFallback [#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` | - | All other avatar fallback props |
### AvatarIndicator [#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` | - | All other div HTML attributes |
### AvatarStatus [#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` | - | All other div HTML attributes |
### AvatarGroup [#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 [#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` | - | All other tooltip content props |