# Avatar

Representação visual de uma pessoa, empresa ou sistema, com imagem, iniciais ou ícone.

> Documentação do Sinapse DS. Snippets shadcn usam os componentes do seu projeto (`@/components/ui/*`); snippets HTML usam as classes `itps-*` do CSS Sinapse (`/css/<versão>/`, veja `/comecar.md`). Componentes do site de documentação não fazem parte do DS.

- Categoria: Data Display
- Status: stable

## Em cada stack

- HTML e Astro: Classes `itps-*` do CSS Sinapse, com todas as variantes desta página.
- React e Vue: Componentes padrão do shadcn (`avatar`) com o tema Sinapse: cores, fonte e raio vêm do tema, e as variantes `itps-*` desta página existem só no HTML.

**React/Next (shadcn/ui)**

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

export function AvatarExample() {
  return (
    <Avatar>
      <AvatarImage src="/examples/avatar-user.svg" alt="Maria Silva" />
      <AvatarFallback>MS</AvatarFallback>
    </Avatar>
  )
}
```

**Vue 3/Nuxt 4 (shadcn-vue)**

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

<template>
  <Avatar>
    <AvatarImage src="/examples/avatar-user.svg" alt="Maria Silva" />
    <AvatarFallback>MS</AvatarFallback>
  </Avatar>
</template>
```

**HTML (copy-first)**

```html
<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

O comando instala o Avatar da sua stack com o tema Sinapse. Configure o registry uma vez por projeto em [Comece por aqui](/comecar).

**terminal · React/Next**

```sh
pnpm dlx shadcn@latest add @sinapse/avatar
```

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/avatar.json
```

Sem shadcn, não há instalação por componente: use o CSS Sinapse e as classes da API copy-first desta página.

## Uso

Em React/Next com shadcn/ui e Vue 3/Nuxt 4 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 Vue 3/Nuxt 4 | 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.

**HTML (copy-first)**

```html
<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">Pequeno, 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">Médio, 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">Grande, 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.