Avatar

The Avatar component is used to represent users, entities, or teams. It can display images, abbreviated text, or serve as a container for icons.

With the Avatar List container, you can easily achieve stacked display of team members.

Basic Usage

The most common usage is to pass a src prop to display an image. When the image fails to load or is not provided, the component automatically falls back to displaying the text from the text prop.

💡 Smart Truncation: If the text contains Chinese characters, it automatically extracts the first character; if it's pure English, it takes the first three letters and capitalizes them.

<TAvatar src="/avatar.png"></TAvatar>
<TAvatar text="Zhang San"></TAvatar>
<TAvatar text="Alex" color="blue-lt"></TAvatar>
<TAvatar text="WK" color="purple-lt"></TAvatar>
<TAvatar text="Li Si" src="/404.png"></TAvatar>

Shape

The component uses a slight rounded corner by default (rounded).

You can change it to a full circle (circle) or a square (square) via the shape prop.

<TAvatar src="/avatar.png" shape="rounded"></TAvatar>
<TAvatar src="/avatar.png" shape="circle"></TAvatar>
<TAvatar src="/avatar.png" shape="square"></TAvatar>

Size

We offer multiple standardized sizes from xs to xl.

Choose the size that best fits your page layout to maintain visual hierarchy.

<TAvatar src="/avatar.png" size="xs"></TAvatar>
<TAvatar src="/avatar.png" size="sm"></TAvatar>
<TAvatar src="/avatar.png" size="md"></TAvatar>
<TAvatar src="/avatar.png" size="lg"></TAvatar>
<TAvatar src="/avatar.png" size="xl"></TAvatar>

Color

For text-fallback avatars, providing a distinct background color helps differentiate users.

Only -lt light variants are recommended.

<TAvatar text="A" color="primary-lt"></TAvatar>
<TAvatar text="B" color="success-lt"></TAvatar>
<TAvatar text="C" color="danger-lt"></TAvatar>
<TAvatar text="D" color="yellow-lt"></TAvatar>
<TAvatar text="E" color="indigo-lt"></TAvatar>

Status & Badges

You can add a status indicator to the avatar to show a user's online/offline status, or to indicate the number of messages they have received.

Thanks to the composability of the component, simply place a TBadge component directly inside the default slot of TAvatar, and it will automatically attach to the edge of the avatar.

🌟 You can also add the avatar-brand class to images or icons to automatically stick to the edge of the avatar.

Show Code

<TAvatar src="/avatar.png">
  <TBadge color="success"></TBadge>
</TAvatar>
<TAvatar text="SA">
  <TBadge color="warning"></TBadge>
</TAvatar>
<TAvatar src="/avatar.png">
  <TBadge color="danger"></TBadge>
</TAvatar>
<TAvatar shape="circle" src="/avatar.png">
  <TBadge color="danger">5</TBadge>
</TAvatar>
<TAvatar src="/avatar.png">
  <IconVip class="avatar-brand" style="color:#d63939"/>
</TAvatar>

Avatar List

When you need to display a group of related users (e.g., project members, like lists), use the TAvatarList container.

You can uniformly set size and shape on the container, and the inner avatars will inherit them automatically.

<TAvatarList size="sm" shape="circle">
  <TAvatar text="Zhao" color="blue-lt"></TAvatar>
  <TAvatar text="Qian" color="azure-lt"></TAvatar>
  <TAvatar text="Sun" color="indigo-lt"></TAvatar>
  <TAvatar text="Li" color="purple-lt"></TAvatar>
</TAvatarList>

Stacked & Max

When stacked is enabled, avatars in the list overlap like playing cards — great for saving space.

Combined with the max prop, you can limit how many avatars are visible.

Excess avatars are hidden and a summary marker (e.g. +3) appears at the end.

<TAvatarList stacked :max="4" size="md" shape="circle">
  <TAvatar src="/avatar.png" v-for="n in 7"></TAvatar>
</TAvatarList>

Interactive Add Button

The TAvatar component supports click event binding, so you can flexibly use it as an action button.

Placing an avatar with an icon at the end of TAvatarList makes it easy to create an "Add Member" or "Load More" interaction, seamlessly blending into the stacked list.

View Code

<script setup>
  import {ref} from 'vue';
  import {IconPlus} from '@tabler/icons-vue';

  const i = ref(3); // initially 3 avatars
</script>

<template>
  <p>Click the + avatar on the right to dynamically increase the number of avatars in the list:</p>
  <TAvatarList stacked size="md" shape="circle">
    <!-- Render existing avatars -->
    <TAvatar src="/avatar.png" v-for="n in i" :key="n"></TAvatar>
    <!-- As a clickable "add" button -->
    <TAvatar text="" @click="i = i + 1" color="secondary-lt">
      <IconPlus/>
    </TAvatar>
  </TAvatarList>
</template>

API

TAvatar Props

Prop	Description	Type	Default
src	The image URL for the avatar.	string	undefined
text	Fallback text when no image is available or image fails to load.	string	''
alt	Native img alt attribute, or aria-label.	string	'Avatar'
size	Avatar size (if wrapped in a List, the List's size takes priority).	'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'	'md'
shape	Avatar shape (if wrapped in a List, the List's shape takes priority).	'rounded' | 'square' | 'circle'	'rounded'
color	Background color for text fallback. Supports theme colors and -lt light variants.	TablerColor	undefined

TAvatarList Props

Prop	Description	Type	Default
stacked	Enable avatar stacking mode — avatars overlap to save space.	boolean	false
max	Maximum number of avatars to display. Excess avatars are hidden and +N is shown. Value 0 means no limit.	number	0
size	Uniform size for all inner avatars.	'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'	'md'
shape	Uniform shape for all inner avatars.	'rounded' | 'square' | 'circle'	'rounded'