# Avatar

A round image or initials that stand for a user, an analyst or a tenant.

```tsx
import { Avatar, AvatarFallback, AvatarImage } from "@zenoxai/ui/components/avatar"

function AvatarDemo() {
  return (
    <>
      <Avatar>
        <AvatarImage src="/favicon.svg" alt="Zenox" />
        <AvatarFallback>ZX</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
    </>
  )
}
```

## Usage

```tsx
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from "@zenoxai/ui/components/avatar"

export function UserAvatar({ user }: { user: User }) {
  return (
    <Avatar>
      <AvatarImage src={user.pictureUrl} alt={user.name} />
      <AvatarFallback>{user.initials}</AvatarFallback>
    </Avatar>
  )
}
```

Always give a fallback. The image shows only once it has loaded; until then, and when the URL is
missing or broken, the fallback shows instead. Use two initials, uppercase, computed in the app
from the name.

An avatar identifies someone; it does not replace their name. In tables, assignee fields and
audit logs, print the name next to it.

## Sizes

`default` (32px) fits lists and table rows. `sm` (24px) fits dense tables and inline mentions;
`lg` (40px) fits profile headers and the account menu.

```tsx
import { Avatar, AvatarFallback } from "@zenoxai/ui/components/avatar"

function AvatarSizes() {
  return (
    <>
      <Avatar size="sm">
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
    </>
  )
}
```

## Group

`AvatarGroup` overlaps the avatars and rings each one with the background color.
`AvatarGroupCount` closes the row with the number of people not shown. Show three or four
avatars at most.

```tsx
import { Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount } from "@zenoxai/ui/components/avatar"

function AvatarStacked() {
  return (
    <AvatarGroup role="group" aria-label="Assigned analysts">
      <Avatar>
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>JL</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>PS</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  )
}
```

## With a badge

`AvatarBadge` places a dot on the bottom-right edge, sized to the avatar. It is `bg-primary` by
default; pass a token class such as `bg-success` for presence. The dot is only a hint: say the
state in text next to the avatar.

```tsx
import { Avatar, AvatarBadge, AvatarFallback } from "@zenoxai/ui/components/avatar"

function AvatarWithBadge() {
  return (
    <div className="flex items-center gap-2">
      <Avatar>
        <AvatarFallback>MR</AvatarFallback>
        <AvatarBadge className="bg-success" />
      </Avatar>
      <div className="flex flex-col">
        <span className="text-sm font-medium">Marina Rocha</span>
        <span className="text-xs text-text-secondary">On call</span>
      </div>
    </div>
  )
}
```

## Accessibility

- Set `alt` on `AvatarImage` to the person's or tenant's name. When the name is printed next to
  the avatar, `alt=""` avoids reading it twice.
- Screen readers read the fallback initials as letters. When the name is not visible, label the
  surrounding element, as the group example does with `role="group"` and `aria-label`.
- `AvatarBadge` has no text. Never let it be the only place a state appears.

## API reference

`import { ... } from "@zenoxai/ui/components/avatar"`

### Avatar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| render | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, AvatarRootState>` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |
| size | `"default" \| "sm" \| "lg"` | `default` | Diameter: `sm` 24px, `default` 32px, `lg` 40px. |

### AvatarImage

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| keepMounted | `boolean` | `false` | Whether the image element stays mounted and loads in place instead of being preloaded. Supports `loading="lazy"` and optimized image components such as `next/image`. |
| onLoadingStatusChange | `((status: ImageLoadingStatus) => void)` |  | Callback fired when the loading status changes. |
| render | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, AvatarImageState>` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

### AvatarFallback

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| delay | `number` | `0` | How long to wait before showing the fallback. Specified in milliseconds. |
| render | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, AvatarFallbackState>` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component.  Accepts a `ReactElement` or a function that returns the element to render. |

### AvatarGroup

No props of its own.

### AvatarGroupCount

No props of its own.

### AvatarBadge

No props of its own.