Avatar

Core Idea

Exibe uma imagem de usuário com fallback automático (iniciais) quando a imagem falha ou não carrega, com suporte a indicador de status (badge) e agrupamento visual de múltiplos avatares.

Key Concepts

• AvatarImage / AvatarFallback: AvatarFallback renderiza automaticamente quando AvatarImage falha ao carregar (comportamento herdado do Base UI Avatar).
• AvatarBadge: indicador posicionado no canto inferior direito do avatar (ex. status online, ícone de "+").
• AvatarGroup / AvatarGroupCount: agrupa múltiplos Avatar com sobreposição visual; AvatarGroupCount mostra "+N" restantes.
• size: "default" | "sm" | "lg" no componente Avatar.

Code Examples

<Avatar>
  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" className="grayscale" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

• O que demonstra: uso básico com fallback de iniciais.

<Avatar>
  <AvatarImage src="https://github.com/evilrabbit.png" alt="@evilrabbit" />
  <AvatarFallback>ER</AvatarFallback>
  <AvatarBadge className="bg-green-600 dark:bg-green-800" />
</Avatar>

• O que demonstra: badge de status (ex. "online") sobreposto ao avatar via className de cor.

<AvatarGroup className="grayscale">
  <Avatar>...</Avatar>
  <Avatar>...</Avatar>
  <Avatar>...</Avatar>
  <AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>

• O que demonstra: grupo de avatares sobrepostos com contador de avatares extras não exibidos.

<DropdownMenuTrigger render={<Button variant="ghost" size="icon" className="rounded-full" />}>
  <Avatar>
    <AvatarImage src="https://github.com/shadcn.png" alt="shadcn" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
</DropdownMenuTrigger>

• O que demonstra: Avatar como trigger de menu dropdown (padrão comum de menu de conta de usuário).

Reference Tables

Componente	Prop	Type	Default
Avatar	size	"default" | "sm" | "lg"	"default"
AvatarImage	src, alt	string	-
AvatarFallback	className	string	-
AvatarBadge	className	string	-
AvatarGroup	className	string	-
AvatarGroupCount	className	string	-

Anti-patterns

• Confiar só em src sem AvatarFallback: sem fallback, uma imagem quebrada deixa o avatar vazio/sem semântica.
• Usar Badge genérico em vez de AvatarBadge: AvatarBadge já resolve posicionamento absoluto correto; recriar isso manualmente é redundante.

Code Examples (Composition)

Avatar
├── AvatarImage
├── AvatarFallback
└── AvatarBadge

AvatarGroup
├── Avatar (×N)
└── AvatarGroupCount

Key Takeaways

1. AvatarFallback é obrigatório na prática, não decorativo: cobre falha de carregamento de imagem.
2. AvatarBadge resolve indicador de status sem CSS manual de posicionamento.
3. AvatarGroup + AvatarGroupCount é o padrão para "equipe/participantes" com limite visível.
4. grayscale como classe é usado nos exemplos para dar um visual neutro consistente entre light/dark.

Connects To

• DropdownMenu: Avatar como trigger é o padrão de menu de perfil de usuário.
• Empty (ch062): EmptyMedia variant="default" frequentemente contém um Avatar ou AvatarGroup.
• Item (ch071): ItemMedia também suporta Avatar como conteúdo de mídia em listas.