---
title: Avatar
description: A person as a circle with initials, a project or service as a square tile with an icon.
---

```tsx
import { Avatar } from "@openperf/deft";

import { Preview } from "../../src/Preview";

export default function AvatarBasic() {
  return (
    <Preview>
      <Avatar.Root>AB</Avatar.Root>
    </Preview>
  );
}
```

- Use an avatar to identify a person, project or service next to its name.
- Pass initials or an icon as children. They stay visible while `src` loads and if it fails.
- Give `alt` with `src` when the name isn't next to the avatar.

## Shapes

```tsx
import { Avatar } from "@openperf/deft";

import { Preview } from "../../src/Preview";

export default function AvatarShapes() {
  return (
    <Preview>
      <Avatar.Root>AB</Avatar.Root>
      <Avatar.Root shape="square">AB</Avatar.Root>
    </Preview>
  );
}
```

Shape tells the entity type: `circle` for people, `square` for projects and services. Don't use shape as decoration.

## Sizes

```tsx
import { Avatar } from "@openperf/deft";

import { Preview } from "../../src/Preview";

export default function AvatarSizes() {
  return (
    <Preview>
      <Avatar.Root size="xs">AB</Avatar.Root>
      <Avatar.Root size="sm">AB</Avatar.Root>
      <Avatar.Root size="md">AB</Avatar.Root>
      <Avatar.Root>AB</Avatar.Root>
      <Avatar.Root size="xl">AB</Avatar.Root>
    </Preview>
  );
}
```

| Size | Use                              |
| ---- | -------------------------------- |
| `xs` | Waterfall rows, meta lines       |
| `sm` | Table rows, workspace pill       |
| `md` | Pickers                          |
| `lg` | User row, group headers          |
| `xl` | Standalone headers, app identity |

`lg` is the default.

## Tones

```tsx
import { Avatar } from "@openperf/deft";

import { Preview } from "../../src/Preview";

export default function AvatarTones() {
  return (
    <Preview>
      <Avatar.Root>AB</Avatar.Root>
      <Avatar.Root tone="accent">AB</Avatar.Root>
      <Avatar.Root tone="inverse">AB</Avatar.Root>
      <Avatar.Root tone="raised">AB</Avatar.Root>
    </Preview>
  );
}
```

`neutral` is the default. Use `accent` only for the signed-in user and `inverse` for a high-contrast identity such as the workspace pill. `raised` sits on the page colour with a raised shadow, as the OpenPerf tile in a [standalone](/deft/components/standalone) header.

## Group

```tsx
import { Avatar } from "@openperf/deft";

import { Preview } from "../../src/Preview";

export default function AvatarGroup() {
  return (
    <Preview>
      <Avatar.Group>
        <Avatar.Root>AB</Avatar.Root>
        <Avatar.Root>CD</Avatar.Root>
        <Avatar.Root>EF</Avatar.Root>
      </Avatar.Group>
    </Preview>
  );
}
```

Use `Avatar.Group` when several projects or people share one compact slot, such as the projects of a release. It overlaps the avatars and adds a ring in the page colour. Keep their size and shape the same.

## Bridge

```tsx
import { Avatar } from "@openperf/deft";

import { Preview } from "../../src/Preview";

export default function AvatarBridge() {
  return (
    <Preview>
      <Avatar.Bridge
        from={<Avatar.Root shape="square">AB</Avatar.Root>}
        to={<Avatar.Root shape="square">CD</Avatar.Root>}
      />
    </Preview>
  );
}
```

Use `Avatar.Bridge` to show that two apps are connected, such as an OAuth client and OpenPerf on the consent screen. It draws a dashed wire with a check between `from` and `to` and gives avatars passed there a raised shadow. The bridge is hidden from assistive technology, so name both apps in the text next to it.

## API

| Prop | Type | Default | Description |
| - | - | - | - |
| `shape?` | `"circle" \| "square"` | `"circle"` | |
| `size?` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"lg"` | |
| `tone?` | `"neutral" \| "accent" \| "inverse" \| "raised"` | `"neutral"` | |
| `src?` | `string` | - | Image URL. Children show until it loads. |
| `alt?` | `string` | - | Alt text for the image. |
| `children?` | `ReactNode` | - | Fallback: initials or an icon. |
| `from` | `ReactNode` | - | On Bridge. The connecting app. |
| `to` | `ReactNode` | - | On Bridge. The app being connected to. |

Parts: `Root`, `Bridge`, `Group`. Other props of `Group` and `Bridge` go to the native `div`. Built on Base UI [Avatar](https://base-ui.com/react/components/avatar).