# Avatar

> Slug: `avatar` · Category: Display

## When to use
- Represent a user, account, or entity by initials, image, or icon.
- Render a clickable identity affordance (profile menu trigger, account link).
- Use as the leading visual in list rows or headers.

## When NOT to use
- Generic icon-only buttons — use `IconButton`.
- Decorative imagery — use a plain `<img>` with appropriate styling.
- Group of users overlapping — Arrow does not include a stacked-avatar group; build one with multiple `Avatar`s placed via layout utilities if needed.

## Variants & decision tree
- Initials-based -> pass `initials` (max 2 chars; uppercased automatically).
- Photo-based -> pass `image` (provide `a11yLabel` for descriptive alt text).
- Icon-based -> pass `icon` (SVG ReactNode).
- Empty / placeholder -> omit `initials`, `image`, `icon`; renders a neutral silhouette with `tdds-avatar--empty`.
- Sizes: `small` (default), `medium`, `large`, `xlarge`.
- Outline: `none` (default) or `dashed` (e.g., for "add" affordance).

## States
- `actionType="button"` -> wraps in a `<button>` with `aria-label`.
- `actionType="anchor"` -> wraps in `<a href={href}>` with `aria-label`. Provide `href`.
- `focused` -> force-focus on the wrapper (design review).
- Inverse-aware (theme or `inverse` prop).

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `initials` | `string` | — | Up to 2 chars; auto-uppercased. |
| `image` | `string` | — | Image URL (alt comes from `a11yLabel`). |
| `icon` | `ReactNode` | — | SVG icon. |
| `a11yLabel` | `string` | — | Accessible label for image/icon. |
| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'small'` | Visual size. |
| `outline` | `'none' \| 'dashed'` | `'none'` | Outline treatment. |
| `actionType` | `'button' \| 'anchor'` | — | Wrap in interactive element. |
| `actionA11yLabel` | `string` | — | Accessible name for action wrapper (initials are prepended automatically when present). |
| `href` | `string` | — | Required when `actionType="anchor"`. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `focused` | `boolean` | — | Force focus on the wrapper. |

## Usage examples
```tsx
import { Avatar } from 'arrow-react-bootstrap';

// Initials, default size
<Avatar initials="JW" a11yLabel="Joe Watkins" />

// Profile photo as a navigation link
<Avatar
  image="/me.jpg"
  size="medium"
  actionType="anchor"
  href="/profile"
  actionA11yLabel="Open profile"
/>

// Icon-based action button
<Avatar
  icon={<svg viewBox="0 0 24 24"><path d="M12 4v16M4 12h16"/></svg>}
  outline="dashed"
  actionType="button"
  actionA11yLabel="Add user"
/>

// Empty placeholder
<Avatar size="large" a11yLabel="No user assigned" />
```

## Composition
- Pair with `SectionHeader` trailing content for header chrome.
- Use as the leading visual of `ListItem` or `Tile`.
- Trigger a `Menu` or `MenuDropdown` via `actionType="button"` + `aria-haspopup`.

## Accessibility
- Without `a11yLabel`, the avatar is treated as decorative (`aria-hidden`).
- When `actionType` is set, `actionA11yLabel` becomes the wrapper's accessible name; if `initials` are present they are prepended ("JW, Open profile").
- Image avatars use `alt={a11yLabel || ''}`.

## Do / Don't
- Do: provide `a11yLabel` whenever the avatar conveys identity.
- Do: keep initials to two characters (truncated automatically).
- Don't: use `<Avatar>` for arbitrary icons — use `IconButton`.
- Don't: omit `href` when `actionType="anchor"`.
