Preview Updated 2026-05-10

Avatar

Avatar with three-stage fallback (image → initials → icon), 5 sizes, circle/square shapes, and AvatarGroup overlap.

Basic usage

Priority order: a successfully loaded src shows the image; on failure or if no src is provided, fallback / name initials are shown; otherwise a ? placeholder.

CQAL?

<script setup lang="ts">
import { CfAvatar } from '@chufix-design/vue';
</script>

<template>
<CfAvatar src="https://i.pravatar.cc/80?img=12" alt="Avatar" />
<CfAvatar name="Chen Qi" />
<CfAvatar name="Anna Lee" />
<CfAvatar fallback="?" />
</template>

import { CfAvatar } from '@chufix-design/react';

export default function Demo() {
return (
  <>
    <CfAvatar src="https://i.pravatar.cc/80?img=12" alt="Avatar" />
    <CfAvatar name="Chen Qi" />
    <CfAvatar name="Anna Lee" />
    <CfAvatar fallback="?" />
  </>
);
}

Size and shape

Five sizes (xs / sm / md / lg / xl) and two shapes (circle / square).

CQCQCQCQCQ

BSBS

<CfAvatar size="xs" name="Chen Qi" />
<CfAvatar size="sm" name="Chen Qi" />
<CfAvatar size="md" name="Chen Qi" />
<CfAvatar size="lg" name="Chen Qi" />
<CfAvatar size="xl" name="Chen Qi" />

<CfAvatar shape="circle" name="Bob Smith" />
<CfAvatar shape="square" name="Bob Smith" />

<CfAvatar size="xs" name="Chen Qi" />
<CfAvatar size="sm" name="Chen Qi" />
<CfAvatar size="md" name="Chen Qi" />
<CfAvatar size="lg" name="Chen Qi" />
<CfAvatar size="xl" name="Chen Qi" />

<CfAvatar shape="circle" name="Bob Smith" />
<CfAvatar shape="square" name="Bob Smith" />

Fallback priority

The second example points at a non-existent src and falls back to initials computed from name. The last one uses a custom icon.

CQAS🐱

<CfAvatar src="https://i.pravatar.cc/80?img=22" alt="Loaded normally" />
<CfAvatar src="/__intentionally_404__.png" name="Fallback Test" />  <!-- load fails → "FT" -->
<CfAvatar name="Chen Qi" />                                          <!-- "CQ" -->
<CfAvatar name="anna lee smith" />                                   <!-- "AS" -->
<CfAvatar fallback="🐱" />                                            <!-- direct override -->
<CfAvatar>                                                            <!-- custom icon -->
<UserSvg />
</CfAvatar>

<CfAvatar src="https://i.pravatar.cc/80?img=22" alt="Loaded normally" />
<CfAvatar src="/__intentionally_404__.png" name="Fallback Test" />
<CfAvatar name="Chen Qi" />
<CfAvatar name="anna lee smith" />
<CfAvatar fallback="🐱" />
<CfAvatar><UserSvg /></CfAvatar>

AvatarGroup overlap

AvatarGroup arranges avatars in an overlapping row — common for “X people collaborating” lists. spacing controls the overlap (more negative = more overlap).

+5ANBOCIDE+12

<CfAvatarGroup>
<CfAvatar src="https://i.pravatar.cc/80?img=1" />
<CfAvatar src="https://i.pravatar.cc/80?img=2" />
<CfAvatar src="https://i.pravatar.cc/80?img=3" />
<CfAvatar fallback="+5" />
</CfAvatarGroup>

<CfAvatarGroup :spacing="-4">
<CfAvatar size="sm" name="Anna" />
<CfAvatar size="sm" name="Bob" />
<CfAvatar size="sm" name="Cici" />
<CfAvatar size="sm" fallback="+12" />
</CfAvatarGroup>

<CfAvatarGroup>
<CfAvatar src="https://i.pravatar.cc/80?img=1" />
<CfAvatar src="https://i.pravatar.cc/80?img=2" />
<CfAvatar src="https://i.pravatar.cc/80?img=3" />
<CfAvatar fallback="+5" />
</CfAvatarGroup>

<CfAvatarGroup spacing={-4}>
<CfAvatar size="sm" name="Anna" />
<CfAvatar size="sm" name="Bob" />
<CfAvatar size="sm" name="Cici" />
<CfAvatar size="sm" fallback="+12" />
</CfAvatarGroup>

API

Avatar

Prop	Type	Default	Description
`src`	`string`	—	Image URL; auto-falls back on load failure
`alt`	`string`	—	Image alt; falls back to `name` when unset
`name`	`string`	—	Used to compute initials (first letter of first and last words)
`fallback`	`string`	—	Override for the initial text, takes priority over `name`
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Size
`shape`	`'circle' \| 'square'`	`'circle'`	Shape

The default slot (Vue) / children (React) replaces the initials — typically used to drop in an SVG icon.

AvatarGroup

Prop	Type	Default	Description
`spacing`	`number`	`-8`	Horizontal spacing between items; negative values create overlap