# Avatar

> A person or organisation shown as an image or initials, with optional presence.

Category: Data display · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/avatar

Avatar shows who something belongs to. Without an image, or if it fails to load, it shows initials on a tint taken from the name, so a person keeps the same colour everywhere. Tints are mixes of ivory and indigo, so they stay within the Binds palette in every theme.

## Import

```tsx
import { Avatar } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Avatar } from '@bindshq/stance-react';

export function Basic() {
  return (
    <div style={{ display: 'flex', gap: 12 }}>
      <Avatar name="Amara Okafor" />
      <Avatar name="Lukas Novak" />
      <Avatar name="Priya Raman" />
      <Avatar name="Tomás Ferreira" />
      <Avatar name="Hana Sato" />
    </div>
  );
}
```

### Sizes

```tsx
import { Avatar } from '@bindshq/stance-react';

export function Sizes() {
  return (
    <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((s) => (
        <Avatar key={s} name="Priya Raman" size={s} />
      ))}
    </div>
  );
}
```

### Presence

```tsx
import { Avatar } from '@bindshq/stance-react';

export function Status() {
  return (
    <div style={{ display: 'flex', gap: 16 }}>
      <Avatar name="Amara Okafor" size="lg" status="online" />
      <Avatar name="Lukas Novak" size="lg" status="away" />
      <Avatar name="Priya Raman" size="lg" status="busy" statusLabel="In a meeting" />
      <Avatar name="Oliver Grant" size="lg" status="offline" />
    </div>
  );
}
```

### Organisations

Use the square shape for organisations and workspaces.

```tsx
import { Avatar } from '@bindshq/stance-react';

export function Shapes() {
  return (
    <div style={{ display: 'flex', gap: 12 }}>
      <Avatar name="Binds" shape="square" size="lg" />
      <Avatar name="eSignify" shape="square" size="lg" />
      <Avatar name="Northwind Ltd" shape="square" size="lg" />
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Avatar | `name` (required) | `string` | None | Used for initials, tint and the accessible name. |
| Avatar | `src` | `string` | None | Image URL; falls back to initials while loading or on error. |
| Avatar | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | 20, 28, 36, 48 or 64px. |
| Avatar | `shape` | `'circle' \| 'square'` | `'circle'` | Square suits organisations. |
| Avatar | `status` | `'online' \| 'away' \| 'busy' \| 'offline'` | None | Presence dot. |
| Avatar | `statusLabel` | `string` | None | Announced status text; defaults to the status name. |
| Avatar | `decorative` | `boolean` | `false` | Hide from assistive tech when the name is already visible. |

## Accessibility

- Exposed as role="img" named after the person, including status, e.g. "Ada Lovelace (online)".
- The inner image has an empty alt, so the name is not announced twice.
- Set decorative when the name appears as text next to the avatar.
- Presence is announced in text; the coloured dot is visual reinforcement only.

## Guidelines

**Do**

- Show the person’s name next to small avatars.

**Don’t**

- Use avatars as the only way to identify people in dense lists.

## Related

- https://stanceui.com/components/avatar-group
- https://stanceui.com/components/list-item