---
title: Avatar
description: An image, initials, or icon that represents a user.
category: Basic
status: beta
since: 0.3.4
tags: [avatar, identity, profile]
syncStatus: reviewed
verified: true
---

## Usage

### Basic
:::TuffDemoWrapper{demo="AvatarBasicDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar src="https://avatars.githubusercontent.com/u/1?v=4" alt="GitHub user" />
    <TxAvatar name="Talex DreamSoul" />
    <TxAvatar icon="user" />
    <TxAvatar>U</TxAvatar>
  </template>
---
:::

### Sizes
`size` takes a preset name or a custom pixel value.
:::TuffDemoWrapper{demo="AvatarSizesDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar size="small" name="Small" />
    <TxAvatar size="medium" name="Medium" />
    <TxAvatar size="large" name="Large" />
    <TxAvatar size="xlarge" name="Extra Large" />
    <TxAvatar :size="56" name="Custom Size" />
  </template>
---
:::

### Text Avatars
:::TuffDemoWrapper{demo="AvatarTextDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar>AL</TxAvatar>
    <TxAvatar>AB</TxAvatar>
    <TxAvatar>User</TxAvatar>
  </template>
---
:::

### Icon Avatars
:::TuffDemoWrapper{demo="AvatarIconDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar icon="user" />
    <TxAvatar icon="team" />
  </template>
---
:::

### Avatar Group
Avatars beyond `max` collapse into a `+N` avatar.
:::TuffDemoWrapper{demo="AvatarGroupDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatarGroup :max="3" size="small" :overlap="10">
      <TxAvatar name="Talex DreamSoul" />
      <TxAvatar name="Alex Lee" />
      <TxAvatar name="Mira Chen" />
      <TxAvatar name="Noah Park" />
      <TxAvatar name="Lina Song" />
    </TxAvatarGroup>
  </template>
---
:::

### Hover Effects
`hoverEffect` sets each avatar's hover feedback; `spreadOnHover` fans the row apart while the group is hovered.
:::TuffDemoWrapper{demo="AvatarGroupHoverDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatarGroup :overlap="12">
      <TxAvatar v-for="id in 5" :key="id" :src="`https://avatars.githubusercontent.com/u/${id}?v=4`" />
    </TxAvatarGroup>

    <!-- A negative spreadOverlap leaves a gap between avatars -->
    <TxAvatarGroup :overlap="12" spread-on-hover :spread-overlap="-4">
      <TxAvatar v-for="id in 5" :key="id" :src="`https://avatars.githubusercontent.com/u/${id}?v=4`" />
    </TxAvatarGroup>

    <TxAvatarGroup :overlap="12" hover-effect="none">
      <TxAvatar v-for="id in 5" :key="id" :src="`https://avatars.githubusercontent.com/u/${id}?v=4`" />
    </TxAvatarGroup>
  </template>
---
:::

### Overflow Popover
`overflowPopover` reveals the collapsed avatars from `+N`; the `overflow` slot replaces the panel content.
:::TuffDemoWrapper{demo="AvatarGroupPopoverDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatarGroup :max="3" :overlap="12" overflow-popover>
      <TxAvatar v-for="id in 8" :key="id" :src="`https://avatars.githubusercontent.com/u/${id}?v=4`" />
    </TxAvatarGroup>
  </template>
---
:::

### Status
:::TuffDemoWrapper{demo="AvatarStatusDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar status="online" name="Online" />
    <TxAvatar status="offline" name="Offline" />
    <TxAvatar status="busy" name="Busy" />
    <TxAvatar status="away" name="Away" />
  </template>
---
:::

### Best Practices

- Pass `name` to generate identity marks instead of hard-coding initials.
- Provide meaningful `alt` when `src` shows a real user's image.
- Use `status` for presence only; use `TxStatusBadge` for textual system state.
- When a group shows `status`, raise `overlap` or enable `spreadOnHover` so dots stay visible.
- Treat the overflow popover as glance-only; use a list component when members need actions.

## API Reference

### TxAvatar

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | - | Image URL; falls back when it fails to load. |
| `alt` | `string` | - | Image alt text; provide it when `src` shows a real user. |
| `name` | `string` | - | Name used to generate initials. |
| `icon` | `string` | - | Fallback icon name, passed to `TxIcon`. |
| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge' \| number \| \`${number}\` \| \`${number}px\`` | `'medium'` | Preset name or positive pixel size; invalid values are ignored. |
| `status` | `'online' \| 'offline' \| 'busy' \| 'away'` | - | Status dot in the corner, inset to follow `shape`. |
| `shape` | `'circle' \| 'square' \| 'rounded'` | `'circle'` | Avatar shape. |
| `clickable` | `boolean` | `false` | Enables pointer styling, button semantics, and the `click` event. |
| `backgroundColor` | `string` | - | Background of the fallback content. |
| `textColor` | `string` | `'#ffffff'` when `backgroundColor` is set | Text color of the fallback content; applies only with `backgroundColor`. |

#### Events

| Event | Payload | Description |
|------|---------|-------------|
| `click` | - | Fires on click, Enter, or Space when `clickable` is set. |

#### Slots

| Slot | Props | Description |
|------|------|-------------|
| `default` | - | Custom fallback content; takes priority over `icon` and `name`. |

### TxAvatarGroup

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `max` | `number` | child count | Avatars shown before collapsing into `+N`; negative values count as zero. |
| `size` | `AvatarSize` | - | Injected into child avatars that don't set their own `size`. |
| `overlap` | `number \| string` | `8` | How far neighbouring avatars overlap; numbers are px. |
| `hoverEffect` | `'none' \| 'lift'` | `'lift'` | Per-avatar hover feedback; `lift` raises, shadows, and brings the avatar forward. |
| `spreadOnHover` | `boolean` | `false` | Eases the overlap to `spreadOverlap` while the group is hovered. |
| `spreadOverlap` | `number \| string` | `0` | Overlap once spread; negative values leave a gap. |
| `overflowPopover` | `boolean` | `false` | Attaches an overflow popover to `+N`. |
| `overflowPopoverTrigger` | `'hover' \| 'click'` | `'hover'` | How the popover opens. |
| `overflowPopoverPlacement` | `PopoverPlacement` | `'top'` | Popover position relative to `+N`. |

#### Slots

| Slot | Props | Description |
|------|------|-------------|
| `default` | - | `TxAvatar` children or compatible avatar VNodes. |
| `overflow` | `{ nodes: VNode[], count: number }` | Overflow popover panel content; `nodes` are the avatars `max` cut off. |

## Overview

- Content falls back from the image to the default slot, `icon`, initials from `name`, then the default `user` icon; a failed image load falls back the same way.
- Initials are the first characters of the first and last words, uppercased.
- With `clickable`, the root gets `role="button"` and `tabindex="0"`, and Enter / Space emit `click` like a click does.
- In a group, `z-index` rises left to right, so each avatar covers the bottom-right corner — status dot included — of the one before; `lift` brings the hovered avatar forward.
- With `overflowPopover` on and avatars overflowing, `+N` is wrapped in `TxPopover`; otherwise it is a plain avatar with no floating layer.
- Under reduced motion, the hover translate and transitions drop out; the forward stacking and shadow remain.

## Technologies

- The root doesn't clip; the image and fallback layers do, which lets the status dot extend past the shape.
- Group negative margins and `z-index` come from the stylesheet (`--tx-avatar-group-overlap`, `--tx-avatar-group-index`); children only get their ring inline.
- Source: `packages/tuffex/packages/components/src/avatar/`.

<TuffDocSourceLink />

## Customization

| Variable | Written by | Purpose |
|----------|------------|---------|
| `--tx-avatar-size` | custom `size` | Width and height. |
| `--tx-avatar-font-size` | custom `size` | Fallback text and icon size. |
| `--tx-avatar-status-size` | custom `size` | Status dot outer diameter, ring included. |
| `--tx-avatar-status-border` | custom `size` | Status dot ring width. |
| `--tx-avatar-bg` | `backgroundColor` | Fallback background. |
| `--tx-avatar-text` | `textColor` (with `backgroundColor`) | Fallback text color. |
| `--tx-avatar-ring` | caller / theme | Ring color around the status dot and grouped avatars; defaults to `--tx-bg-color`. |
| `--tx-avatar-group-overlap` | `overlap` | Resolved overlap distance. |
| `--tx-avatar-group-spread-overlap` | `spreadOverlap` | Overlap once spread. |
| `--tx-avatar-group-hover-z` | caller / theme | `z-index` of the hovered avatar; defaults to `999`. |
| `--tx-avatar-group-overflow-width` | caller / theme | Overflow panel width before wrapping; defaults to `232px`. |
| `--tx-avatar-group-border` | caller / theme | Ring color of grouped avatars. |

`--tx-avatar-*-preset`, `--tx-avatar-status-diameter`, `--tx-avatar-status-ring`, `--tx-avatar-status-inset`, `--tx-avatar-group-gap`, `--tx-avatar-group-index`, and `--tx-avatar-group-more-z` are internal; don't set them directly.