Avatar

An image element with a fallback for representing the user.

RBX

tsx

1
2
3
4<Avatar>
  <AvatarImage src="/avatars/03.png" alt="@shadcn" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Avatar représente un utilisateur ou un identifiant — image ronde avec fallback texte (typiquement des initiales) affiché pendant le chargement ou en cas d'erreur d'image. C'est un composant purement visuel (pas d'interactivité par lui-même).

Composition :

AvatarImage — le <img> avec aspect-square h-full w-full. Si src échoue à charger, le navigateur affiche le fallback en dessous.
AvatarFallback — un <span> qui affiche des initiales sur fond muted. Rendu visible seulement quand l'image n'est pas chargée / a échoué.
AvatarBadge — pastille de statut (typiquement en ligne / hors ligne) posée en absolute bas-droite. Taille adaptée au size parent.

3 sizes : sm (h-6 w-6, 24px), default (h-8 w-8, 32px), lg (h-10 w-10, 40px). Le size est stocké en data-size sur le root, ce qui permet aux sub-composants (Fallback, Badge) de s'adapter via group-data-[size=…]/avatar:….

AvatarGroup empile plusieurs Avatar avec un -space-x-2 et pose un ring-2 ring-background sur chacun (le look "collé" avec démarcation nette). AvatarGroupCount pour le "+N" quand on n'affiche que les premiers.

Installation

Terminal

$ bext ui add avatar

Usage

tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import { Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup } from "@bext-stack/ui/primitives"

// Avatar simple avec image + fallback initiales
<Avatar>
  <AvatarImage src="/avatars/03.png" alt="@shadcn" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

// Avatar avec badge de statut
<Avatar>
  <AvatarImage src="/avatars/02.png" alt="@rabbit" />
  <AvatarFallback>R</AvatarFallback>
  <AvatarBadge className="bg-emerald-500" />
</Avatar>

// Groupe de 3 avatars + compteur
<AvatarGroup>
  <Avatar><AvatarImage src="/avatars/01.png" alt="Alice" /><AvatarFallback>A</AvatarFallback></Avatar>
  <Avatar><AvatarImage src="/avatars/02.png" alt="Bob" /><AvatarFallback>B</AvatarFallback></Avatar>
  <Avatar><AvatarImage src="/avatars/03.png" alt="Cassandra" /><AvatarFallback>C</AvatarFallback></Avatar>
  <AvatarGroupCount>+8</AvatarGroupCount>
</AvatarGroup>

Anatomy

<Avatar size="sm|default|lg">
  ├── <AvatarImage src="/…" alt="…" />         // image chargée en priorité
  ├── <AvatarFallback>CN</AvatarFallback>       // initiales si img échoue
  └── <AvatarBadge>...</AvatarBadge>            // pastille statut, optionnel

<AvatarGroup>                                    // -space-x-2 + ring-2
  ├── <Avatar>...</Avatar>
  ├── <Avatar>...</Avatar>
  └── <AvatarGroupCount>+3</AvatarGroupCount>

API Reference

Avatar

Prop	Type	Default	Description
size	"sm" \| "default" \| "lg"	"default"	Taille du root : sm=h-6 w-6, default=h-8 w-8, lg=h-10 w-10. Stocké en data-size pour cascade aux sub-composants.
src	string	—	Raccourci (backwards-compat) : si présent sans children, rend AvatarImage + AvatarFallback automatiquement.
fallback	string	—	Raccourci : initiales à afficher via AvatarFallback quand src est utilisé en raccourci.
className	string	—	Classes CSS supplémentaires sur le root .

AvatarImage

Prop	Type	Default	Description
src	string	—	URL de l'image (locale ou HTTP).
alt	string	""	Texte alternatif. Toujours préciser pour a11y — utiliser le nom de l'utilisateur.
className	string	—	Classes CSS. Défaut : aspect-square h-full w-full.

AvatarFallback

Prop	Type	Default	Description
className	string	—	Classes CSS. Défaut : bg-muted text-sm text-muted-foreground.

AvatarBadge

Prop	Type	Default	Description
className	string	—	Pastille absolute bottom-right. Taille selon data-size du parent.

AvatarGroup

Prop	Type	Default	Description
className	string	—	flex -space-x-2 avec ring-2 ring-background sur chaque Avatar enfant.

AvatarGroupCount

Prop	Type	Default	Description
className	string	—	Bulle "+N" (même look qu'un Avatar) pour indiquer les avatars non affichés.

Data Attributes

Attributs qu'on peut cibler en CSS custom pour override le style par état.

Attribute	On	Values	Description
data-slot	chaque sub-composant	"avatar" \| "avatar-image" \| "avatar-fallback" \| "avatar-badge" \| "avatar-group" \| "avatar-group-count"	Sélecteur stable pour styling custom.
data-size	Avatar root	"sm" \| "default" \| "lg"	Cascade aux Fallback (text-xs pour sm) et Badge (h-2, h-2.5, h-3).

Keyboard

Key	Action
`—`	Avatar n'est pas interactif par défaut. Si wrappé dans un ou

Accessibility

Toujours poser un alt descriptif sur AvatarImage — c'est ce que les lecteurs d'écran vont annoncer. Format typique : alt="@shadcn" ou alt="Karim Zribi". Ne pas laisser vide sauf si l'avatar est purement décoratif (jamais en pratique).

AvatarFallback n'est PAS un fallback a11y — juste visuel. Les AT annoncent l'alt de l'AvatarImage même quand l'image ne charge pas.

AvatarBadge visuel : ajouter un texte cachée avec <span class="sr-only">Online</span> pour que le statut soit annoncé.

Dans AvatarGroup, les avatars overlap visuellement. Pour un compte "+N", ajouter aria-label="et N autres" sur le AvatarGroupCount.

Examples

Sizes (sm, default, lg)

tsx

1
2
3<Avatar size="sm"><AvatarImage src="…" /><AvatarFallback>S</AvatarFallback></Avatar>
<Avatar><AvatarImage src="…" /><AvatarFallback>M</AvatarFallback></Avatar>
<Avatar size="lg"><AvatarImage src="…" /><AvatarFallback>L</AvatarFallback></Avatar>

Fallback (aucune image)

CNBXKZ

tsx

1
2
3<Avatar>
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Badge (statut en overlay)

tsx

1
2
3
4
5<Avatar>
  <AvatarImage src="…" alt="Alice" />
  <AvatarFallback>A</AvatarFallback>
  <AvatarBadge className="bg-emerald-500" />
</Avatar>

AvatarGroup (empilement)

tsx

1
2
3
4
5
6<AvatarGroup>
  <Avatar><AvatarImage src="…" alt="A" /><AvatarFallback>A</AvatarFallback></Avatar>
  <Avatar><AvatarImage src="…" alt="B" /><AvatarFallback>B</AvatarFallback></Avatar>
  <Avatar><AvatarImage src="…" alt="C" /><AvatarFallback>C</AvatarFallback></Avatar>
  <AvatarGroupCount>+8</AvatarGroupCount>
</AvatarGroup>

Try it live Open in play

Edit this example live in the bext playground — it compiles and runs entirely in your browser.

src/app/page.tsx 1 file · react · runs in your browser

// An avatar shows a user image, falling back to coloured initials
// when no image is available.
const wrap = {
  width: 44, height: 44, borderRadius: 9999, overflow: "hidden",
  display: "inline-flex", alignItems: "center", justifyContent: "center",
  fontSize: 15, fontWeight: 600, flexShrink: 0,
};

export default function Page() {
  return (
    <main style={{ maxWidth: 640, margin: "0 auto", padding: "48px 20px", fontFamily: "Inter, system-ui, sans-serif" }}>
      <h1 style={{ letterSpacing: "-0.02em", marginBottom: 4 }}>Avatar</h1>
      <p style={{ color: "#64748b", marginTop: 0 }}>A user image with an initials fallback.</p>
      <div style={{ display: "flex", alignItems: "center", gap: 14, marginTop: 22 }}>
        <span style={{ ...wrap, background: "#f1f5f9" }}>
          <img src="https://i.pravatar.cc/88?img=12" alt="User" width={44} height={44} style={{ width: "100%", height: "100%", objectFit: "cover" }} />

The React idiom — same UI, for comparison.

← Aspect Ratio Badge →

On This Page