Avatar — Sinapse Design System

Maria Silva Paciente

import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from '@/components/ui/avatar'

export function AvatarExample() {
  return (
    <Avatar>
      <AvatarImage src="/avatars/maria-silva.png" alt="Maria Silva" />
      <AvatarFallback>MS</AvatarFallback>
    </Avatar>
  )
}

<script setup lang="ts">
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from '@/components/ui/avatar'
</script>

<template>
  <Avatar>
    <AvatarImage src="/avatars/maria-silva.png" alt="Maria Silva" />
    <AvatarFallback>MS</AvatarFallback>
  </Avatar>
</template>

<div class="flex min-w-0 items-center gap-3">
  <span class="itps-avatar itps-avatar--user" role="img" aria-label="Maria Silva">
    <span class="itps-avatar__initials" aria-hidden="true">MS</span>
  </span>
  <span class="min-w-0">
    <span class="block truncate text-sm font-semibold text-foreground">Maria Silva</span>
    <span class="block truncate text-xs text-muted-foreground">Paciente</span>
  </span>
</div>

Instalação

Instale Avatar da sua stack e rode o comando individual ITpS em seguida. O comando itps add avatar é theme-only: ele valida o slug e confirma que o contrato visual vem do tema ITpS, das classes copy-first e dos snippets desta página.

terminal · React/Next

pnpm dlx shadcn@latest add avatar
pnpm dlx github:ITPS/sinapse-ui-cli add avatar

terminal · Vue3/Nuxt4

pnpm dlx shadcn-vue@latest add avatar
pnpm dlx github:ITPS/sinapse-ui-cli add avatar

O comando individual adapta só este componente; não instala o catálogo inteiro.

Uso

Em React/Next com shadcn/ui e Vue3/Nuxt4 com shadcn-vue, use Avatar, AvatarImage e AvatarFallback. O fallback deve ser curto e legível quando a imagem falhar ou ainda não tiver carregado.

Para HTML ou wrappers finos, use itps-avatar com iniciais quando houver nome confiável. Mantenha o nome visível próximo do avatar para não depender só da imagem, iniciais ou ícone.

Exemplos

Estrutura

Peça	React/Next e Vue3/Nuxt4	HTML
Raiz	`Avatar`	`itps-avatar`
Imagem	`AvatarImage`	`itps-avatar__image`
Fallback	`AvatarFallback`	`itps-avatar__initials` ou `itps-avatar__icon`
Tamanho	classe utilitária	`itps-avatar--sm`, `itps-avatar--md`, `itps-avatar--lg`

Tamanhos e fallback

Use os modificadores de tamanho para manter consistência visual. Sem modificador, o avatar tem 56px.

João Silva Small, 32px

Ana Costa Medium, 40px

Marcos Lima Large, 80px

Pessoa sem iniciais Fallback com ícone de usuário

<div class="grid gap-4 sm:grid-cols-2">
  <div class="flex min-w-0 items-center gap-3">
    <span class="itps-avatar itps-avatar--user itps-avatar--sm" role="img" aria-label="João Silva">
      <span class="itps-avatar__initials" aria-hidden="true">JS</span>
    </span>
    <span class="min-w-0">
      <span class="block truncate text-sm font-semibold text-foreground">João Silva</span>
      <span class="block truncate text-xs text-muted-foreground">Small, 32px</span>
    </span>
  </div>

  <div class="flex min-w-0 items-center gap-3">
    <span class="itps-avatar itps-avatar--user itps-avatar--md" role="img" aria-label="Ana Costa">
      <span class="itps-avatar__initials" aria-hidden="true">AC</span>
    </span>
    <span class="min-w-0">
      <span class="block truncate text-sm font-semibold text-foreground">Ana Costa</span>
      <span class="block truncate text-xs text-muted-foreground">Medium, 40px</span>
    </span>
  </div>

  <div class="flex min-w-0 items-center gap-3">
    <span class="itps-avatar itps-avatar--user itps-avatar--lg" role="img" aria-label="Marcos Lima">
      <span class="itps-avatar__initials" aria-hidden="true">ML</span>
    </span>
    <span class="min-w-0">
      <span class="block truncate text-sm font-semibold text-foreground">Marcos Lima</span>
      <span class="block truncate text-xs text-muted-foreground">Large, 80px</span>
    </span>
  </div>

  <div class="flex min-w-0 items-center gap-3">
    <span class="itps-avatar itps-avatar--user" role="img" aria-label="Pessoa sem iniciais">
      <i class="itps-avatar__icon ti ti-user" aria-hidden="true"></i>
    </span>
    <span class="min-w-0">
      <span class="block truncate text-sm font-semibold text-foreground">Pessoa sem iniciais</span>
      <span class="block truncate text-xs text-muted-foreground">Fallback com ícone de usuário</span>
    </span>
  </div>
</div>

API copy-first

Classe/atributo	Uso
`itps-avatar`	Wrapper circular do avatar.
`itps-avatar--user`, `itps-avatar--company`, `itps-avatar--system`	Papel visual da entidade.
`itps-avatar--sm`, `itps-avatar--md`, `itps-avatar--lg`	Tamanhos semânticos.
`itps-avatar__image`	Imagem recortada em círculo.
`itps-avatar__initials`	Fallback textual curto.
`itps-avatar__icon`	Fallback com ícone quando não houver iniciais confiáveis.
`role="img"`	Expõe o avatar como imagem quando ele identifica uma pessoa.
`aria-label`	Nomeia o avatar quando o nome não está no texto vizinho.
`aria-hidden="true"`	Evita leitura duplicada quando o nome já aparece ao lado.

Acessibilidade

Use role="img" e aria-label quando o avatar identifica uma pessoa. Use aria-hidden="true" quando o nome já aparece ao lado do avatar e a leitura duplicada atrapalhar.

Não dependa apenas do ícone para identificar a pessoa. Não use Avatar para comunicar status; mantenha status em texto visível ou em outro componente específico.