Avatar

Representa visualmente um usuário, sistema ou entidade — com iniciais, foto ou ícone.

Regras de design: quadrado por padrão (sistema geométrico), borda preta sempre, cor determinística por hash do nome, status como bloco quadrado no canto SE.

Uso

vue

<script setup lang="ts">
import { Avatar, AvatarPlate, AvatarGroup } from '@halfbyte-labs/maka'
</script>

<template>
  <Avatar name="Marina Souza" />
</template>

Tamanhos

Seis tamanhos, de xs (24px) a 2xl (120px). A borda escala junto: 1px no xs, 1.5px até md, 2px no lg+.

vue

<Avatar size="xs"  name="Marina Souza" />
<Avatar size="sm"  name="Marina Souza" />
<Avatar size="md"  name="Marina Souza" />
<Avatar size="lg"  name="Marina Souza" />
<Avatar size="xl"  name="Marina Souza" />
<Avatar size="2xl" name="Marina Souza" />

Formas

square é o padrão do sistema. Use soft para cards genéricos; round apenas para perfis pessoais explícitos.

vue

<Avatar shape="square" name="Ana Lima" />  <!-- padrão -->
<Avatar shape="soft"   name="Ana Lima" />  <!-- cards genéricos -->
<Avatar shape="round"  name="Ana Lima" />  <!-- perfil pessoal -->

Cores

A paleta tem 7 entradas. Por padrão (color="auto") a cor é determinística — mesmo name sempre gera a mesma cor, em qualquer tela.

vue

<Avatar color="blue"  name="Blue"  />
<Avatar color="navy"  name="Navy"  />
<Avatar color="cyan"  name="Cyan"  />
<Avatar color="light" name="Light" />
<Avatar color="lime"  name="Lime"  />
<Avatar color="gray"  name="Gray"  />   <!-- identidade desconhecida / anônimo -->
<Avatar color="black" name="Black" />   <!-- sistemas / bots -->

Contraste de texto:

Texto branco (fg.inverse): blue, navy, black
Texto preto (fg): cyan, light, lime, gray

Cor determinística (hash)

O mesmo name sempre produz a mesma cor. Três instâncias do mesmo avatar — mesma cor, garantido. Sem Math.random().

vue

<!-- Sempre a mesma cor para "Fernanda Costa" -->
<Avatar name="Fernanda Costa" size="xl" />
<Avatar name="Fernanda Costa" size="lg" />
<Avatar name="Fernanda Costa" size="md" />
<Avatar name="Fernanda Costa" size="sm" />

Iniciais

Derivadas automaticamente do name: primeiro + último inicial (sempre 2 chars). Nome único → 2 primeiras letras.

vue

<Avatar name="João Silva" />                   <!-- JS -->
<Avatar name="Ana Carolina Lima Pinheiro" />   <!-- AP (não ACLP) -->
<Avatar name="Marina" />                       <!-- MA -->
<Avatar name="" />                             <!-- ? + cor gray automático -->

Com foto

Passe src para exibir a imagem. Se carregar com erro, o componente cai automaticamente nas iniciais — sem flash, sem quebra.

vue

<!-- Foto com formas diferentes -->
<Avatar name="Thiago Nox" src="https://..." shape="square" size="xl" />
<Avatar name="Thiago Nox" src="https://..." shape="soft"   size="lg" />
<Avatar name="Thiago Nox" src="https://..." shape="round"  size="md" />

<!-- Foto quebrada → iniciais automaticamente -->
<Avatar name="Foto Quebrada" src="https://url-invalida.com/foto.jpg" />

Status de presença

Bloco quadrado no canto SE (~28% da largura do avatar). A forma do status acompanha a forma do avatar — quadrado em square/soft, círculo em round.

vue

<Avatar name="João Silva"  status="online"  />
<Avatar name="Ana Lima"    status="away"    />
<Avatar name="Carlos Melo" status="dnd"     />
<Avatar name="Paula Reis"  status="offline" />

Status	Cor	Significado
`online`	lime	Ativo, presença em tempo real
`away`	amber	Inativo há > 5 min, agenda livre
`dnd`	red	Não perturbar / em reunião
`offline`	gray	Desconectado / nunca esteve online

O status sempre inclui aria-label em PT-BR. Nunca dependa apenas da cor para comunicar presença (acessibilidade e daltonismo).

Status em todos os tamanhos

Status com forma round

vue

<!-- Com round, o dot também fica redondo -->
<Avatar name="João Silva" shape="round" status="online" />

Badge

Contador numérico no canto NE — mono, preto com lime. Acima de 99 exibe 99+; acima de 999, 1K+.

vue

<Avatar name="João Silva"  :badge="3"    />
<Avatar name="Ana Lima"    :badge="42"   />
<Avatar name="Carlos Melo" :badge="130"  />  <!-- exibe 99+  -->
<Avatar name="Paula Reis"  :badge="1500" />  <!-- exibe 1K+  -->
<Avatar name="Sofia Braga" badge="novo"  />  <!-- texto livre -->

Em xs e sm, evite usar badge e status simultaneamente — eles se sobrepõem visualmente.

Status + Badge juntos

Em md+, status (SE) e badge (NE) convivem sem colisão.

vue

<Avatar name="Fernanda Costa" size="md"  status="online" :badge="5"  />
<Avatar name="Ricardo Moura"  size="lg"  status="dnd"    :badge="12" />
<Avatar name="Beatriz Lima"   size="xl"  status="away"   :badge="99" />

Estados

Selecionado

Outline 2px azul, offset 2px. Útil em pickers de usuário ou listas de seleção.

vue

<Avatar name="João Silva" :selected="true" />
<Avatar name="Carlos"     :selected="true" shape="round" />

Desabilitado

opacity: 0.45 + grayscale(0.8). O componente adiciona aria-disabled="true" e bloqueia interações.

vue

<Avatar name="João Silva"  :disabled="true" />
<Avatar name="Ana Lima"    :disabled="true" status="online" />
<Avatar name="Carlos Melo" :disabled="true" :badge="3" />

Interativo

Use as="button" ou as="a" para tornar o avatar clicável. Hover aplica translateY(-1px), active aplica scale(0.96), focus aplica outline azul.

vue

<!-- Botão -->
<Avatar name="João Silva" as="button" @click="abrirPerfil" />

<!-- Link -->
<Avatar name="Ana Lima" as="a" href="/perfil/ana" />

<!-- Com href → 'a' automático -->
<Avatar name="Carlos" href="/perfil/carlos" />

<!-- Interativo com overlays -->
<Avatar name="Marina" as="button" status="online" :badge="3" @click="abrirChat" />

AvatarPlate

Composição de avatar + nome + meta + ação à direita. Ideal para listas de usuários, headers de card e comentários.

vue

<AvatarPlate>
  <template #avatar>
    <Avatar name="Marina Souza" size="md" status="online" />
  </template>
  <template #name>Marina Souza</template>
  <template #meta>Designer · São Paulo</template>
  <template #trailing>
    <Button size="sm" variant="outline">Ver perfil</Button>
  </template>
</AvatarPlate>

AvatarGroup

Stack de avatares com sobreposição de −28%. Quando há mais que max avatares, o excesso vira um chip +N em preto/lime. Hover em qualquer avatar o levanta 2px.

vue

<!-- Stack básico -->
<AvatarGroup :max="4" size="md">
  <Avatar name="Marina Souza" />
  <Avatar name="João Silva"   />
  <Avatar name="Ana Lima"     />
</AvatarGroup>

<!-- Com excesso → chip +N -->
<AvatarGroup :max="4" size="md">
  <Avatar name="Marina Souza"   />
  <Avatar name="João Silva"     />
  <Avatar name="Ana Lima"       />
  <Avatar name="Carlos Melo"    />
  <Avatar name="Paula Reis"     />
  <Avatar name="Rodrigo Faria"  />
  <Avatar name="Fernanda Costa" />
  <Avatar name="Beatriz Lima"   />
</AvatarGroup>

<!-- Fundo escuro — troca o ring de separação -->
<AvatarGroup :max="4" size="md" :on-dark="true">
  <Avatar name="Marina Souza" />
  <Avatar name="João Silva"   />
</AvatarGroup>

Anônimo / identidade desconhecida

Use color="gray" para usuários sem identidade (contas removidas, visitantes anônimos, bots genéricos).

vue

<Avatar name=""           color="gray"  />           <!-- visitante -->
<Avatar name="Anônimo"    color="gray"  />           <!-- sem identidade -->
<Avatar name="[removido]" color="gray"  :disabled="true" />
<Avatar name="Bot"        color="black" />           <!-- sistemas -->

Props — Avatar

Prop	Tipo	Padrão	Descrição
`name`	`string`	—	Obrigatório. Usado para iniciais, hash de cor e `aria-label`
`src`	`string`	—	URL da foto. Fallback automático para iniciais se errar
`alt`	`string`	`""`	Alt da `<img>`. Deixe vazio — o wrapper já tem o `aria-label`
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`	`'md'`	Tamanho do avatar
`shape`	`'square' \| 'soft' \| 'round'`	`'square'`	Forma dos cantos
`color`	`AvatarColor \| 'auto'`	`'auto'`	Cor de fundo. `'auto'` = hash determinístico do nome
`status`	`'online' \| 'away' \| 'dnd' \| 'offline'`	—	Indicador de presença (canto SE)
`statusLabel`	`string`	PT-BR automático	Label acessível do status
`badge`	`number \| string`	—	Contador no canto NE. `>99` → `99+`, `>999` → `1K+`
`selected`	`boolean`	`false`	Outline 2px azul de seleção
`disabled`	`boolean`	`false`	Opacidade 45% + grayscale + `aria-disabled`
`as`	`'span' \| 'a' \| 'button'`	`'span'`	Elemento raiz. Use `button`/`a` para avatares clicáveis
`href`	`string`	—	Força `as="a"` automaticamente
`aria-label`	`string`	`name`	Sobrescreve o label acessível padrão

Props — AvatarPlate

Prop	Tipo	Padrão	Descrição
`size`	`'md' \| 'lg'`	`'md'`	Escala dos textos de nome e meta

Slots: #avatar, #name, #meta, #trailing

Props — AvatarGroup

Prop	Tipo	Padrão	Descrição
`max`	`number`	`4`	Máximo de avatares visíveis. Extras viram chip `+N`
`size`	`AvatarSize`	`'md'`	Tamanho aplicado a todos os avatares do grupo
`onDark`	`boolean`	`false`	Troca o ring de separação para fundos escuros

Events — Avatar

Evento	Payload	Descrição
`click`	`MouseEvent`	Emitido ao clicar (quando `as="button"` ou `as="a"`)

Acessibilidade

name é obrigatório — vira aria-label do wrapper.
Foto usa alt="" (decorativa), o wrapper já tem o label.
Status tem aria-label em PT-BR automático (online, ausente, não perturbar, offline).
Avatares clicáveis usam as="button" ou as="a", nunca <div onClick>.
disabled aplica aria-disabled="true" e bloqueia onClick.
Grupo com +N inclui aria-label="mais N pessoas".

Avatar ​

Uso ​

Tamanhos ​

Formas ​

Cores ​

Cor determinística (hash) ​

Iniciais ​

Com foto ​

Status de presença ​

Status em todos os tamanhos ​

Status com forma round ​

Badge ​

Status + Badge juntos ​

Estados ​

Selecionado ​

Desabilitado ​

Interativo ​

AvatarPlate ​

AvatarGroup ​

Anônimo / identidade desconhecida ​

Props — Avatar ​

Props — AvatarPlate ​

Props — AvatarGroup ​

Events — Avatar ​

Acessibilidade ​