# Avatar

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - avatar.variants — `avatarVariants` is the cva confi…
- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…
- avatar.variants — `avatarVariants` is the cva confi…

- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…

- avatar.variants — `avatarVariants` is the cva confi…

- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…

- avatar.variants — `avatarVariants` is the cva confi…

- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…
- [avatar.variants](./avatar.variants.md) — `avatarVariants` is the cva config that powers the `<Avatar>` chassis component (`<AvatarImage>` and `<AvatarFallback>`…

## Purpose

`<Avatar>` is the chassis circular image holder built on `@radix-ui/react-avatar`. It ships as a family of three components — `<Avatar>` (root), `<AvatarImage>`, `<AvatarFallback>` — that compose into the conventional shadcn avatar pattern. Per the shadcn skill rule, ALWAYS pair an `<AvatarImage>` with an `<AvatarFallback>` — Radix swaps the fallback in when the image source fails to load OR when no source is supplied. An Avatar without a fallback flashes empty while loading, then disappears silently on a 404 — both are bugs.

The root `<Avatar>` exposes a `size` axis with four rungs (`sm` / `default` / `lg` / `xl`) using Tailwind's `size-*` shorthand so width and height stay in lockstep, preventing off-by-one ratio bugs that arise when consumers set width and height independently.

## Features

- Four sizes via the `size` axis (`sm` / `default` / `lg` / `xl`) using Tailwind `size-*`.
- Three composition primitives — `Avatar` (root), `AvatarImage`, `AvatarFallback`.
- Radix-managed image-loading state machine — `<AvatarFallback>` swaps in automatically when the image source fails or has not yet loaded.
- `aspect-square object-cover` on `<AvatarImage>` so portrait / landscape sources crop centrally rather than distorting.
- Forwards refs to the underlying Radix elements on every sub-component.

## Usage: Basic Example

```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@suaveplan/react-ui";

export function UserAvatar() {
    return (
        <Avatar>
            <AvatarImage src="/avatar.png" alt="Jane Doe" />
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
    );
}
```

## Usage: Advanced Example

```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@suaveplan/react-ui";

interface AvatarStackUser {
    readonly id: string;
    readonly name: string;
    readonly avatarUrl?: string;
}

export function AvatarStack({ users }: { users: AvatarStackUser[] }) {
    return (
        <div className="flex -space-x-2">
            {users.slice(0, 3).map((user) => (
                <Avatar key={user.id} size="lg" className="border-2 border-background">
                    {user.avatarUrl != null ? (
                        <AvatarImage src={user.avatarUrl} alt={user.name} />
                    ) : null}
                    <AvatarFallback>
                        {user.name
                            .split(" ")
                            .slice(0, 2)
                            .map((part) => part[0])
                            .join("")}
                    </AvatarFallback>
                </Avatar>
            ))}
        </div>
    );
}
```

## API Reference

### `<Avatar>`

`forwardRef<…, AvatarProps>` — root container backed by `@radix-ui/react-avatar` `Root`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | `"sm" \| "default" \| "lg" \| "xl"` | `"default"` | Diameter — uses Tailwind `size-*`. |
| _Radix props_ | _Radix-typed_ | — | All `AvatarPrimitive.Root` props. |

### `<AvatarImage>`

`forwardRef<…, AvatarImageProps>` — image source. Cover-fits inside the circular surface. Radix swaps in `<AvatarFallback>` automatically when the source fails to load.

### `<AvatarFallback>`

`forwardRef<…, AvatarFallbackProps>` — fallback surface. Per shadcn skill rule, REQUIRED in every Avatar. Typical contents are user initials (one or two letters) or an icon.

#### Errors

The Avatar components do NOT call `useTranslation()` so they do not interact with the i18n provider. The image's `alt` attribute and the fallback content are consumer-provided; consumers wanting translated alt text should pass `t('user.avatar.alt')` at the call site.

## Implementation Notes

- `size-*` is used at the root so width and height change together — the historical bug where consumers passed `w-10 h-12` and produced an ellipse cannot occur with this API.
- Radix manages the image-loading state machine: `<AvatarImage>` is hidden until the image loads successfully, and `<AvatarFallback>` is shown until the image is confirmed loaded. Without a fallback, the avatar surface is empty during the load window and after a load failure.
- `<AvatarFallback>` accepts an optional `delayMs` prop (forwarded from Radix) — when set, the fallback is suppressed for that many ms so quick image loads don't cause a brief fallback flash.
- The chassis does NOT ship an `AvatarGroup` component — that pattern is consumer composition (`<div className="flex -space-x-2">…</div>` over a list of `<Avatar>`s) and shipping it as a discrete primitive forecloses the many layout variations consumers want.
- All sub-components forward refs to the underlying Radix elements so consumers can attach event listeners, focus management, or animation controls without wrapping.