# Avatar

```tsx
import { Avatar } from '@tangible/ui';
```

Interactive docs and examples: [Avatar in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/primitives-avatar--docs).

## Avatar props

| Prop | Type | Default | Description |
| - | - | - | - |
| `className?` | `string` | | Additional CSS class |
| `color?` | `"amber" \| "blue" \| "coral" \| "cyan" \| "emerald" \| "lime" \| "orange" \| "pink" \| "slate" \| "teal" \| "violet"` | | Explicit color for initials background (otherwise derived from name via `stringToGenerativeColor`). `slate` is the neutral fallback for name-less avatars — deliberately not in the hash bag, grey means "no identity", not a flavour. |
| `indicator?` | `React.ReactNode` | | Status indicator element (icon, badge, etc.) |
| `indicatorLabel?` | `string` | | Accessible label for the indicator (e.g., "Online", "Verified", "3 notifications") |
| `indicatorPosition?` | `"bottom-left" \| "bottom-right" \| "top-left" \| "top-right"` | `'bottom-right'` | Position of the indicator |
| `labels?` | `AvatarLabels` | | Overridable strings for i18n. |
| `name?` | `string` | | User's name - used for alt text and generating initials fallback |
| `shape?` | `"circle" \| "square"` | `'circle'` | Shape of the avatar |
| `size?` | `"lg" \| "md" \| "sm" \| "xl" \| "xs" \| "xxl"` | `'md'` | Size of the avatar |
| `src?` | `string` | | Image source URL |
| `tooltip?` | `boolean` | | When true, wraps the avatar with a Tooltip showing the `name`. Helps sighted users discover the user's name on hover/focus. Has no effect when `name` is not provided. |

### Avatar.Group

Also exported as `AvatarGroup`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | | Children (Avatar components) |
| `className?` | `string` | | Additional CSS class |
| `groupLabel?` | `(total: number, visible: number) => string` | | Custom label function for i18n. Receives total and visible counts. Default: "N users" or "N users, showing M". |
| `labels?` | `AvatarGroupLabels` | | Overridable strings for i18n. Coexists with `groupLabel` — `groupLabel` takes precedence for the group aria-label when provided. |
| `max?` | `number` | | Maximum avatars to show before "+N" overflow |
| `overlap?` | `boolean` | `true` | Whether avatars overlap (default: true) |
| `shape?` | `"circle" \| "square"` | | Shape for all avatars in the group |
| `size?` | `"lg" \| "md" \| "sm" \| "xl" \| "xs" \| "xxl"` | | Size for all avatars in the group |

## Examples

Stories: With Image, With Initials, Placeholder, Image Error → Initials Fallback, Sizes, Initials Sizes, Shapes, Color Palette, Dark Mode Palette, Consistent Colors (Same Name = Same Color), With Indicator, Indicator Positions, Online Status (Accessible), Group, Group With Overflow, Group No Overlap, Group Sizes, Group Initials, Comment Author, Profile Card, Members List, With Tooltip, Image Only (Decorative) ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/primitives-avatar--docs)).

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-avatar-size`
- `--tui-avatar-radius`
- `--tui-avatar-bg`
- `--tui-avatar-fg`
- `--tui-avatar-border`
- `--tui-avatar-indicator-bg`
- `--tui-avatar-indicator-fg`
- `--tui-avatar-overflow-bg`
- `--tui-avatar-overflow-fg`
- `--tui-avatar-group-overlap`
- `--tui-avatar-group-gap`
- `--tui-avatar-group-border-width`
- `--tui-avatar-group-border-color`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/primitives-avatar--docs