# Avatar

> User representation with image, initials fallback, grouping, and status indicator.

- Available in: `@sisyphos-ui/react`, `@sisyphos-ui/vue`, `@sisyphos-ui/angular`
- Docs: https://www.sisyphosui.com/docs/components/avatar

## Installation

Pick the framework binding that matches your stack:

```bash
pnpm add @sisyphos-ui/react   # React 18+
pnpm add @sisyphos-ui/vue     # Vue 3+
pnpm add @sisyphos-ui/angular # Angular 17+
```

## Import

```tsx
import "@sisyphos-ui/react/styles.css";
import { Avatar } from "@sisyphos-ui/react";
```

## Framework usage

### React 18+

```tsx
import { Avatar } from "@sisyphos-ui/react";

export const Profile = () => <Avatar name="Volkan Günay" color="primary" />;
```

### Vue 3+

```vue
<script setup lang="ts">
import { Avatar } from "@sisyphos-ui/vue";
</script>

<template>
  <Avatar name="Volkan Günay" color="primary" />
</template>
```

### Angular 17+

```ts
import { Component } from "@angular/core";
import { Avatar } from "@sisyphos-ui/angular";

@Component({
  selector: "app-profile",
  standalone: true,
  imports: [Avatar],
  template: `<sui-avatar name="Volkan Günay" color="primary" />`,
})
export class ProfileComponent {}
```

## Examples

### Default

```tsx
import { Avatar } from "@sisyphos-ui/react";

export function Example() {
  return (
    <div className="flex items-center gap-4">
      <Avatar src="https://i.pravatar.cc/100?img=1" alt="Ada" />
      <Avatar name="Linus Torvalds" />
      <Avatar name="Grace Hopper" color="success" />
      <Avatar name="Alan Turing"  color="info"    shape="rounded" />
      <Avatar name="Hedy Lamarr"  color="warning" shape="square" />
    </div>
  );
}
```

### Avatar group

Stack avatars and collapse overflow into a `+N` chip.

```tsx
import { Avatar, AvatarGroup } from "@sisyphos-ui/react";

export function Example() {
  return (
    <AvatarGroup max={3}>
      <Avatar src="https://i.pravatar.cc/100?img=2" alt="A" />
      <Avatar src="https://i.pravatar.cc/100?img=3" alt="B" />
      <Avatar src="https://i.pravatar.cc/100?img=4" alt="C" />
      <Avatar name="Dora" />
      <Avatar name="Eva"  />
      <Avatar name="Frida" />
    </AvatarGroup>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| src | `string` | — | Image source; falls back to initials/fallback when omitted or on load error. |
| alt | `string` | — | Alt text for the image; also labels the fallback. Required for accessibility when `src` is set. |
| name | `string` | — | Display name used to derive initials (and as the label when `alt` is omitted). |
| initialsMax | `number` | `2` | Maximum number of initials derived from `name`. |
| fallback | `ReactNode` | — | Override fallback content (icon, custom text); takes precedence over derived initials. |
| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Avatar dimensions. |
| color | `"neutral" \| "primary" \| "success" \| "error" \| "warning" \| "info"` | `"neutral"` | Semantic color applied to the fallback background. |
| shape | `"circular" \| "rounded" \| "square"` | `"circular"` | Shape variant. |

## Accessibility notes

- The image's alt text resolves as `alt ?? name ?? ""` — pass `alt` (or at least `name`) whenever `src` is set; with neither, the image is treated as decorative.
- Fallback content (initials, icon, or custom node) carries `aria-label={alt ?? name}` so screen readers announce the person instead of raw initials.
- When the image fails to load, the component automatically swaps to the labeled fallback — no broken-image announcement.
- The image is `draggable={false}` to avoid accidental drag interactions.

<!-- exports: { "Avatar": "@sisyphos-ui/react" } -->