# Avatar

A user or entity's profile image with a text fallback.

- Category: Core Elements
- Page: https://wunderui.com/components/avatar
- Tier: Free

## Install

```bash
npx wunderui-cli add avatar
```

## Import

```tsx
import { Avatar, AvatarBadge, AvatarBadgeStatus, AvatarColor, AvatarFallback, AvatarImage, AvatarLabel, AvatarLabelProps, PersonCell, UserInfo } from "@/components/ui/avatar"
```

## Minimal usage

Then use it:

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

export function Owner() {
  return (
    <Avatar color="indigo">
      <AvatarFallback>NL</AvatarFallback>
    </Avatar>
  )
}
```

Expected result: You should see one round 36 px avatar with the indigo tint and the initials NL.

## Usage

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

export function Example() {
  return (
    <Avatar color="indigo">
      <AvatarFallback>NL</AvatarFallback>
    </Avatar>
  )
}
```

## When to use

### Use Avatar for

- Showing who a person is next to their name, a comment or an activity entry
- Showing what a workspace, team or project is, with a square avatar
- The account button of an app bar, or a choice of a person in a picker

### Use something else

- [Avatar Group](https://wunderui.com/components/avatar-group) for several people in a row, composed by hand with a hover effect or passed as data with people and a limit
- [Person Cell](https://wunderui.com/components/person-cell) for an avatar with a name and a role in a table or a list

## Keyboard

A plain avatar is not interactive and has no keyboard behaviour. An interactive avatar is a native button.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to or away from an interactive avatar. A disabled one is skipped. |
| `Enter` or `Space` | Presses the avatar, for example to open an account menu or to choose a person. |

## Behavior

What the avatar does with state, content, the DOM and motion.

- **Image and fallback:** The fallback stays in place until the image has loaded, and when the URL fails; you can delay it to avoid a flash for a fast image. The tint sits on the frame behind the image.
- **Size:** The size sets the frame (24, 28, 36, 40 or 44 px) and scales initials, icon and presence dot with it. Initials and counts are centred on cap height, so they look centred in any font.
- **Presence dot:** The badge sits on the top right corner: its centre is on the edge of a circle, or on the rounded corner of a square. With a status it is an image named by the status; override with aria-label.
- **Interactive:** An interactive avatar is a button with aria-pressed from selected. Hover draws a 3 px halo in the page tone, a press the subtle tone, keyboard focus the focus ring, and disabled dims it to 40 %.
- **Selected:** Selected adds a check badge on the top right corner, where the presence dot sits, and keeps the subtle halo on an interactive avatar.
- **Names for screen readers:** Initials are real text, so a screen reader reads NL before the name. When the name is printed beside the avatar, hide the avatar from assistive technology and give the image an empty alt.
- **Motion:** The avatar has no motion of its own: the halo of an interactive avatar changes at once.
- **Reduced motion:** Nothing animates, so reduced motion needs no fallback here. In Avatar Group the hover lift is switched off.

## Anatomy

- `Avatar`: The round or square frame in five sizes. Set a colour for tinted initials or the primary variant for a filled one; interactive makes it a button, selected adds a check badge and disabled dims it.
- `AvatarImage`: The photo, an img with src and alt. It shows once loaded; until then, or when the URL fails, the fallback stays in place.
- `AvatarFallback`: Initials or an icon, shown while the image loads or when there is none. The text size follows the avatar size.
- `AvatarBadge`: A dot on the top right corner, centred on the circle's edge or the square's corner. A status sets a presence dot with a shape per status and an accessible name that defaults to the status.
- `AvatarLabel`: An avatar with a name and a second line, and optionally a capacity bar or a control at the end. It is a plain div. It replaces PersonCell and UserInfo, which still render the same row.
- `PersonCell`
- `UserInfo`
- `Check`

## Best practices

### When to use

- Use an Avatar to show who a person or workspace is, next to their name. For several people in little space, use Avatar Group.

### Do

- Always add a fallback with initials, also when there is an image. It covers the moment before the photo loads and a broken image URL.
- Use a circle for a person and a square for an entity such as a workspace, team or project, so the shape already tells which one it is.
- Keep one colour per person. The tints are theme tokens, so initials stay readable in dark mode.
- Show presence with the badge and say it in text where it matters, such as Away next to the name. Each status has its own shape, so colour is never the only signal.
- Give an interactive avatar an accessible name with aria-label, for example Account menu, Nora Lindgren. Its initials are not a name.
- Next to a single 20 px line of text use size="3xs", so the avatar is as tall as the text.

### Don't

- Don't resize an avatar with your own size classes. Pick one of the sizes: initials, icon and presence dot scale with it.
- Don't use colour to carry status or meaning. Tone is an identity colour; status needs the presence dot, a word, or both.
- Don't combine selected with a presence dot. The check badge and the dot sit on the same corner, so one hides the other.

## API reference

### Avatar

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the frame, merged with its own. Use it for a one-off colour such as the dark tint of a chosen row, not for the size. |
| color | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" \| "grey" |  | A soft tint for initials: the tint colour behind and the matching tint text colour on top. Use one hue per person, and do not combine it with `variant="primary"`. |
| disabled | boolean |  | Dims an interactive avatar to 40 % and removes pointer events. It has no effect on a plain avatar. |
| interactive | boolean |  | Renders the avatar as a `button` with hover, pressed and focus states. Pass `aria-label`, because the initials are not a name. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the avatar, for example with a link: `render={<a href="/team/nora" />}`. Accepts an element or a function that returns one. |
| selected | boolean |  | Marks the avatar as chosen: a check badge on the top right corner. With `interactive` it also draws the subtle halo and sets `aria-pressed`. |
| shape | "circle" \| "square" |  | `circle` for a person, `square` for an entity such as a workspace, team or project. The square has a medium corner radius. |
| size | "3xs" \| "sm" \| "xs" \| "default" \| "lg" \| "xl" |  | The size of the frame: `sm` is 24 px, `xs` 28 px, `default` 36 px, `lg` 40 px and `xl` 44 px. Initials, icon and presence dot scale with it. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the frame, or a function that returns them from the state of the avatar. |
| variant | "plain" \| "primary" |  | `plain` is a muted fill with a hairline border. `primary` fills the frame with the primary colour and sets the initials in the colour on primary. |

Also accepts React.HTMLAttributes attributes.

### AvatarBadge

| Prop | Type | Default | Description |
|---|---|---|---|
| status | "available" \| "busy" \| "away" \| "dnd" \| "offline" \| "unknown" |  | The presence dot: `available`, `busy`, `away`, `dnd`, `offline` or `unknown`. Each has its own shape and an accessible name by default (`Available`, `Busy`, `Away`, `Do not disturb`, `Offline`, `Status unknown`). Without `status` the badge is an empty dot for your own content. |

Also accepts React.HTMLAttributes attributes.

### AvatarFallback

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the fallback, merged with its own. |
| delay | number | 0 | How long to wait before the fallback shows, in milliseconds. Use it so the initials do not flash while a fast image loads. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the element of the fallback. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the fallback, or a function that returns them from its state. |

Also accepts React.HTMLAttributes attributes.

### AvatarImage

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the image, merged with its own. |
| keepMounted | boolean | false | Keeps the image in the DOM while it is not shown, for example while it loads or when it failed. |
| onLoadingStatusChange | ((status: ImageLoadingStatus) => void) |  | Called with `idle`, `loading`, `loaded` or `error` whenever the loading status of the image changes. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the `img` element, for example with the image component of your framework. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the image, or a function that returns them from its state. |

Also accepts React.ImgHTMLAttributes attributes.

### AvatarLabel

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | string |  | The name, cut to one line. The initials are taken from it when there is no photo and no `initials`. Required. |
| capacity | { value: number; label?: React.ReactNode } |  | A load bar under the text, as `value` 0 to 100 and an optional `label` such as 25h. It is a meter: green up to 80 %, yellow up to 100 %, red above. |
| className | string |  | Extra classes on the row. Use them for padding, corners and a width. |
| color | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" \| "grey" |  | The tint behind the initials, as on Avatar. Without it the avatar is grey. |
| compact | boolean |  | Smaller text, 12 px for the name and 11 px for the second line, with a semibold name. On by default when there is a capacity bar. |
| initials | string |  | The text in the avatar without a photo. Default: the first letters of the first two words of the name. |
| nameWeight | "medium" \| "semibold" |  | The weight of the name: `medium` or `semibold`. Default: semibold when compact, medium otherwise. |
| size | "default" \| "lg" \| "xl" | "default" | The avatar: `default` 36 px, `lg` 40 px or `xl` 44 px. |
| src | string |  | The address of a photo. It replaces the initials and has empty alternative text, because the name stands beside it. |
| subtext | React.ReactNode |  | The line under the name, such as a role or an email. |
| tight | boolean | true | Removes the 2 px between the name and the second line. |
| trailing | React.ReactNode |  | A control at the end of the row, such as an IconButton that opens a menu. |

### PersonCell

| Prop | Type | Default | Description |
|---|---|---|---|
| person* | Person |  |  |
| capacity | { value: number; label?: React.ReactNode } |  | Size=lg adds a capacity bar: value 0–100 and a label like "32h". |
| className | string |  |  |
| role | React.ReactNode |  |  |

### UserInfo

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | string |  |  |
| className | string |  |  |
| color | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" \| "grey" |  |  |
| initials | string |  |  |
| onMenu | () => void |  |  |
| src | string |  |  |
| subtext | string |  |  |
| variant | "person" \| "sidebar" \| "menu" | "person" | person (42px avatar, 14px name) · sidebar (40px, 12px, padded) · menu (adds a ⋮ button) |

## Examples

### Types: initials or icon, circle or square

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

export function Example() {
  return (
    <Avatar color="indigo">
      <AvatarFallback>NL</AvatarFallback>
    </Avatar>
  )
}
```

### Appearance: plain, primary and tints

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

export function Example() {
  return (
    <Avatar>
      <AvatarFallback>NL</AvatarFallback>
    </Avatar>
  )
}
```

### Sizes: 24, 28, 36, 40 and 44 px

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

export function Example() {
  return (
    <Avatar color="indigo">
      <AvatarFallback>NL</AvatarFallback>
    </Avatar>
  )
}
```

### Presence: one shape per status

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

export function Example() {
  return (
    <Avatar size="xl" color="indigo">
      <AvatarFallback>NL</AvatarFallback>
      <AvatarBadge status="available" />
    </Avatar>
  )
}
```

### States: default, selected and disabled

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

export function Example() {
  return (
    <Avatar interactive color="indigo" aria-label="Nora Lindgren">
      <AvatarFallback>NL</AvatarFallback>
    </Avatar>
  )
}
```

### Label: an avatar with a name and a second line

```tsx
import { AvatarLabel } from "@wunderui/react"

export function Person() {
  return <AvatarLabel name="Nora Lindgren" subtext="Design lead" color="purple" size="xl" nameWeight="semibold" />
}
```

## In context

### Account menu: the avatar is the trigger

The avatar is the account button in the app bar and carries the presence dot. The menu header repeats the name and email.

```tsx
import { useState } from "react"
import { LogOut, Settings, User } from "lucide-react"
import { Avatar, AvatarBadge, AvatarFallback } from "@/components/ui/avatar"
import { Separator } from "@/components/ui/separator"
import { Switch } from "@/components/ui/switch"

const ROW =
  "flex h-9 w-full items-center gap-2 rounded-md px-2 text-left text-sm hover:bg-bg-page active:bg-bg-subtle focus-ring"

export function Example() {
  const [open, setOpen] = useState(true)
  const [dark, setDark] = useState(false)

  return (
    <div className="flex flex-col gap-2">
      <div className="flex h-16 items-center justify-between rounded-xl border border-border bg-card px-5">
        <span className="text-sm font-semibold">Inbox</span>
        <Avatar
          interactive
          color="indigo"
          aria-label="Account menu, Nora Lindgren"
          aria-haspopup="menu"
          aria-expanded={open}
          onClick={() => setOpen(!open)}
        >
          <AvatarFallback>NL</AvatarFallback>
          <AvatarBadge status="available" />
        </Avatar>
      </div>
      {open && (
        <div className="w-60 self-end rounded-lg border border-border bg-popover p-1 [--surface:var(--popover)]">
          <div className="flex items-center gap-3 px-2 py-2">
            <Avatar color="indigo" aria-hidden>
              <AvatarFallback>NL</AvatarFallback>
            </Avatar>
            <div className="flex flex-col">
              <span className="text-sm font-medium">Nora Lindgren</span>
              <span className="text-xs text-text-secondary">info@wunderui.com</span>
            </div>
          </div>
          <Separator className="my-1" />
          <button type="button" className={ROW}>
            <User className="size-4" />
            Profile
          </button>
          <button type="button" className={ROW}>
            <Settings className="size-4" />
            Settings
          </button>
          <div className="flex h-9 items-center justify-between px-2 text-sm">
            Dark mode
            <Switch checked={dark} onCheckedChange={setDark} aria-label="Dark mode" />
          </div>
          <Separator className="my-1" />
          <button type="button" className={ROW}>
            <LogOut className="size-4" />
            Log out
          </button>
        </div>
      )}
    </div>
  )
}
```

### Assignee picker: choose a person

The chosen person's row is highlighted, and the avatar turns dark with white initials.

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

const TEAMMATES = [
  { id: "nora", name: "Nora Lindgren", detail: "You, 4 open", initials: "NL", color: "indigo" },
  { id: "daniel", name: "Daniel Okafor", detail: "Engineering, 2 open", initials: "DO", color: "purple" },
  { id: "priya", name: "Priya Raman", detail: "Billing, 6 open", initials: "PR", color: "pink" },
  { id: "tomas", name: "Tomás Ferreira", detail: "Support, 3 open", initials: "TF", color: "green" },
] as const

// The avatar of the chosen row is a dark tint with white initials.
const CHOSEN = {
  indigo: "bg-indigo-600 text-primary-foreground",
  purple: "bg-purple-600 text-primary-foreground",
  pink: "bg-pink-600 text-primary-foreground",
  green: "bg-green-600 text-primary-foreground",
}

export function Example() {
  const [chosen, setChosen] = useState("nora")

  return (
    <div className="w-80 rounded-lg border border-border bg-popover p-1 [--surface:var(--popover)]">
      <p className="flex h-7 items-center px-2 text-xs text-text-tertiary">Assign to</p>
      {TEAMMATES.map((person) => {
        const on = person.id === chosen
        return (
          <button
            key={person.id}
            type="button"
            aria-pressed={on}
            onClick={() => setChosen(person.id)}
            className={`flex h-12 w-full items-center gap-3 rounded-md px-2 text-left hover:bg-bg-page focus-ring ${on ? "bg-bg-subtle" : ""}`}
          >
            <Avatar size="xs" color={person.color} className={on ? CHOSEN[person.color] : undefined} aria-hidden>
              <AvatarFallback>{person.initials}</AvatarFallback>
            </Avatar>
            <span className="flex flex-col">
              <span className="text-sm font-medium">{person.name}</span>
              <span className="text-xs text-text-secondary">{person.detail}</span>
            </span>
          </button>
        )
      })}
    </div>
  )
}
```

### Team list: presence next to a status word

Presence shows on the avatar and as a word, so colour is never the only signal.

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

const TEAM = [
  { name: "Nora Lindgren", role: "Product lead", initials: "NL", color: "indigo", status: "available", label: "Available" },
  { name: "Daniel Okafor", role: "Engineering", initials: "DO", color: "purple", status: "busy", label: "In a meeting" },
  { name: "Priya Raman", role: "Billing", initials: "PR", color: "pink", status: "away", label: "Away" },
  { name: "Tomás Ferreira", role: "Design", initials: "TF", color: "green", status: "dnd", label: "Do not disturb" },
  { name: "Maya Kessler", role: "Research", initials: "MK", color: "orange", status: "offline", label: "Offline" },
] as const

export function Example() {
  return (
    <ul className="divide-y divide-border overflow-hidden rounded-xl border border-border bg-card">
      {TEAM.map((member) => (
        <li key={member.name} className="flex items-center gap-3 px-4 py-2.5">
          <Avatar color={member.color} aria-hidden>
            <AvatarFallback>{member.initials}</AvatarFallback>
            <AvatarBadge status={member.status} />
          </Avatar>
          <span className="flex flex-col">
            <span className="text-sm font-medium">{member.name}</span>
            <span className="text-xs text-text-secondary">{member.role}</span>
          </span>
          {/* The status is also written out, so the dot is never the only signal. */}
          <span className="ml-auto text-xs font-medium text-text-secondary">{member.label}</span>
        </li>
      ))}
    </ul>
  )
}
```

### Workspace switcher: square avatars for entities

Workspaces and teams use square avatars, people keep circles. The open trigger takes the page tone.

```tsx
import { useState } from "react"
import { ChevronsUpDown, Plus } from "lucide-react"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Separator } from "@/components/ui/separator"

const WORKSPACES = [
  { id: "wunderui", name: "WunderUI", detail: "Owner, 12 members", initials: "WU", color: "indigo" },
  { id: "brightside", name: "Brightside Studio", detail: "Member, 5 members", initials: "BS", color: "purple" },
  { id: "lumen", name: "Lumen Labs", detail: "Admin, 31 members", initials: "LL", color: "green" },
] as const

export function Example() {
  const [open, setOpen] = useState(true)
  const [current, setCurrent] = useState<string>("wunderui")
  const workspace = WORKSPACES.find((item) => item.id === current) ?? WORKSPACES[0]

  return (
    <div className="flex w-72 flex-col gap-2">
      <button
        type="button"
        aria-haspopup="listbox"
        aria-expanded={open}
        onClick={() => setOpen(!open)}
        className="flex h-[52px] items-center gap-2.5 rounded-xl border border-border bg-card px-2 text-left hover:bg-bg-page focus-ring"
      >
        <Avatar shape="square" color={workspace.color} aria-hidden>
          <AvatarFallback>{workspace.initials}</AvatarFallback>
        </Avatar>
        <span className="flex flex-col">
          <span className="text-sm font-medium">{workspace.name}</span>
          <span className="text-xs text-text-secondary">{workspace.detail}</span>
        </span>
        <ChevronsUpDown className="ml-auto size-4 text-text-tertiary" />
      </button>
      {open && (
        <div className="rounded-2xl border border-border bg-popover p-2 [--surface:var(--popover)]">
          {WORKSPACES.map((item) => (
            <button
              key={item.id}
              type="button"
              aria-pressed={item.id === current}
              onClick={() => setCurrent(item.id)}
              className="flex h-[52px] w-full items-center gap-3 rounded-xl px-2 text-left hover:bg-bg-page aria-pressed:bg-bg-subtle focus-ring"
            >
              <Avatar shape="square" color={item.color} aria-hidden>
                <AvatarFallback>{item.initials}</AvatarFallback>
              </Avatar>
              <span className="text-sm font-medium">{item.name}</span>
            </button>
          ))}
          <Separator className="my-1" />
          <button type="button" className="flex h-9 w-full items-center gap-2 rounded-xl px-2 text-sm hover:bg-bg-page focus-ring">
            <Plus className="size-4" />
            Create workspace
          </button>
        </div>
      )}
    </div>
  )
}
```

### 20 px: as tall as a one-line text row

`size="3xs"` is 20 px with 9 px initials, for a name in a 20 px line (an assignee cell, a person tag).

```tsx
<Avatar size="3xs" color="purple">
  <AvatarFallback>NL</AvatarFallback>
</Avatar>
```

## For AI agents

`get_component("avatar")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
