# Avatar

Represents a person, contact, or wallet with an image, initials, or an icon.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Avatar.tsx)

Figma: [Avatar](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=1418-13100)

## Overview

An avatar is a circle that holds an image, or initials or an icon in secondary text on a neutral fill. It leads a list row or a modal header.

## Examples

### Basic

```tsx
import { Avatar } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Avatar.Root>
      <Avatar.Fallback>J</Avatar.Fallback>
    </Avatar.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Avatar/Basic.tsx)

### Size

Set `size` to `16`, `24`, `32`, `40` (default), `48`, or `64`.

```tsx
import { Avatar, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['16', '24', '32', '40', '48', '64'] as const).map((size) => (
        <Avatar.Root key={size} size={size}>
          <Avatar.Fallback>J</Avatar.Fallback>
        </Avatar.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Avatar/Size.tsx)

### Icon

Put an icon in `Avatar.Fallback` for a wallet or app. It renders at 16px in a `24` or `32` avatar, and at 20px in a `40` avatar.

```tsx
import { Avatar, style } from '@tempoxyz/ds'
import { Wallet } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <div {...styles.row()}>
      {(['24', '32', '40'] as const).map((size) => (
        <Avatar.Root key={size} size={size}>
          <Avatar.Fallback>
            <Wallet />
          </Avatar.Fallback>
        </Avatar.Root>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Avatar/Icon.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Avatar } from '@tempoxyz/ds'

<Avatar />

<Avatar.Root>
  <Avatar.Image />
  <Avatar.Fallback />
</Avatar.Root>
```

## Guidelines

### When to Use

* Represent a person or organization beside their name, such as a contact in Send or a merchant in activity.
* Represent a wallet or app with an icon, such as a connected wallet in a list row.

### When Not to Use

* Use [Identicon](/docs/components/identicon) for an account known only by its address.
* Use [TokenLogo](/docs/components/token-logo) for the icon of a token or asset.
* Use [IconTile](/docs/components/icon-tile) for the icon above a centered modal title.

### Choose Avatar or Identicon

* **Person or Organization (Avatar):** A name, shown as initials.
* **Address Only (Identicon):** An account known only by its address.
* **Mixed List (Avatar.Fallback):** A mix of both, with an identicon in the fallback.

### Always Include a Fallback

* **People and organizations:** Use initials.
* **Wallets and apps:** Use an icon.
* **Accounts known by address:** Use an [Identicon](/docs/components/identicon) with `size="fill"`.

**Do:** Give every avatar a fallback, such as initials, an icon, or an `Identicon`.

```tsx
/**
 * Do example for "Always Include a Fallback" on the Avatar page.
 * Give every avatar a fallback, such as initials, an icon, or an `Identicon`.
 * @module
 */
import { Avatar, Identicon, style } from '@tempoxyz/ds'
import { Wallet } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Avatar size="40">
        <Avatar.Fallback>AL</Avatar.Fallback>
      </Avatar>
      <Avatar size="40">
        <Avatar.Fallback>
          <Wallet />
        </Avatar.Fallback>
      </Avatar>
      <Avatar size="40">
        <Avatar.Fallback>
          <Identicon address="0x71C7656EC7ab88b098defB751B7401B5f6d8976F" aria-hidden size="fill" />
        </Avatar.Fallback>
      </Avatar>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

**Don't:** Leave an empty circle.

```tsx
/**
 * Don't example for "Always Include a Fallback" on the Avatar page.
 * Don't leave an empty circle.
 * @module
 */
import { Avatar, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <Avatar size="40" />
      <Avatar size="40" />
      <Avatar size="40" />
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

### Pair the Avatar With a Name

Hide the avatar with `aria-hidden` beside a visible name, so screen readers don't read the initials and the name.

**Do:** Show the name, and a detail such as an email, beside each avatar.

```tsx
/**
 * Do example for "Pair the Avatar With a Name" on the Avatar page.
 * Show the name, and a detail such as an email, beside each avatar.
 * @module
 */
import { Avatar, style } from '@tempoxyz/ds'

const contacts = [
  ['JC', 'Jane Cooper', 'jane@example.com'],
  ['AL', 'Ada Lovelace', 'ada@example.com'],
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      {contacts.map(([initials, name, email]) => (
        <div key={name} {...styles.row()}>
          <Avatar aria-hidden size="40">
            <Avatar.Fallback>{initials}</Avatar.Fallback>
          </Avatar>
          <div {...styles.text()}>
            <span {...styles.name()}>{name}</span>
            <span {...styles.detail()}>{email}</span>
          </div>
        </div>
      ))}
    </div>
  )
}

namespace styles {
  export const detail = style({ color: 'content.secondary', typography: 'body.b3' })

  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })

  export const name = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })

  export const text = style({ display: 'flex', flexDirection: 'column', gap: '4' })
}
```

**Don't:** Ask people to pick a recipient from initials alone.

```tsx
/**
 * Don't example for "Pair the Avatar With a Name" on the Avatar page.
 * Don't ask people to pick a recipient from pictures or initials alone.
 * @module
 */
import { Avatar, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      {['JC', 'AL', 'MR', 'JD'].map((initials) => (
        <Avatar key={initials} size="40">
          <Avatar.Fallback>{initials}</Avatar.Fallback>
        </Avatar>
      ))}
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

### Match Size to the Layout

* **Inline and Dense Rows (24):** Inline with text and in dense table rows.
* **List Rows (32):** List rows, such as recipients in a modal.
* **Header Lead (40):** The default. The lead of a header.

### Use Initials for People and Icons for Wallets

* **Person or Contact (Initials):** One or two initials from the name.
* **Wallet or App (Icon):** One icon from the library, in the text color.

In a modal, leave out brand colors, so every avatar keeps the neutral fill.

## Content

* **Initials:** Use one or two, such as AL for Ada Lovelace. The fallback uppercases them.
* **Organizations:** Use the first letter of the name, not an unfamiliar abbreviation.
* **Wallets and apps:** Use an icon instead of letters.

## Accessibility

Renders a `<span>` that holds the fallback.

### Semantics

* **Avatar.Fallback (span):** Plain text. Screen readers read the initials as written.
* **Icon Fallback (aria-hidden):** Icons without an `aria-label` are hidden, so the avatar is silent.

### Keyboard

An avatar takes no focus. To open a profile, wrap the avatar and name in one link, and let the name label it.

### Your Responsibilities

* **Hide a Duplicate Avatar (aria-hidden):** If the name is visible beside the avatar, hide the root so screen readers skip the initials.
* **Name a Standalone Avatar (aria-label):** If no name is visible, set `role="img"` and an `aria-label` with the full name on the root.

## Related

[Identicon](/docs/components/identicon)

Use for accounts known by address.

[TokenLogo](/docs/components/token-logo)

Use for token icons.

[IconTile](/docs/components/icon-tile)

Use for the icon above a centered modal title.

[ListGroup](/docs/components/list-group)

Use for lists of people and accounts.
