# Avatar

> A person or a thing, as an image over its initials. The initials are in the server HTML and the image covers them once it loads, so there is no empty circle and no broken image. A presence dot, a square for things, and a group that folds the rest into +N.

Section: Primitives. Docs: https://entrepta.vercel.app/docs/components/avatar

## Install

```bash
npx @entrepta/cli@latest add avatar
```

Files: `primitives/avatar.tsx`, `lib/icon.tsx`.
npm packages: `@phosphor-icons/react`, `class-variance-authority`.
Comes with: `icon-lib`.

## Usage

```tsx
import { Avatar, AvatarGroup } from "@/components/entrepta/avatar"
import { RobotIcon } from "@phosphor-icons/react"

<Avatar name="Anna Maria" src="/me.jpg" />
<Avatar name="Anna Maria" size="lg" status="online" />
<Avatar name="Anna Maria" size="xl" emphasis="ring" />
<Avatar name="deploy bot" shape="square" color="brand" icon={RobotIcon} />

// next to a written name, hide it so the name is read once
<Avatar name="Anna Maria" size="sm" aria-hidden /> anna maria

<AvatarGroup max={4} aria-label="contributors">
  {people.map((p) => <Avatar key={p.login} name={p.name} src={p.avatar} />)}
</AvatarGroup>

// on a card, the dot and the overlaps cut out of the card's color
<Card className="[--cutout:var(--bg-card)]">…</Card>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | - | Who or what it is. Gives the initials and the name screen readers hear. Required |
| `src` | `string` | - | An image. The initials show until it loads, and stay if it fails |
| `size` | `"sm" \| "md" \| "lg" \| "xl"` | "md" | 24, 32, 48 or 96px. In a group, the group's size unless set here |
| `shape` | `"circle" \| "square"` | "circle" | A circle for people, a square for things: a team, a bot, a repo |
| `color` | `"neutral" \| "brand"` | "neutral" | The fill behind the initials. Brand is for you, or what you feature |
| `status` | `"online" \| "away" \| "busy" \| "offline"` | - | A presence dot in the corner, announced with the name |
| `icon` | `Icon \| ReactElement` | - | A glyph in place of the initials, for a thing rather than a person |
| `emphasis` | `"none" \| "ring"` | "none" | A brand ring for the active profile, or the person the page is about |
| `max` | `number` | - | How many show before the rest fold into +N. The row never wraps, so set it when the list can grow (AvatarGroup) |