Avatar

Exibe a representação visual de um usuário com suporte a imagem, iniciais e ícone de fallback. Use `mk-avatar` em perfis, listas e comentários.

O mk-avatar exibe a identificação visual de um usuário. Quando uma imagem é fornecida via src, ela é exibida com prioridade. Se a imagem falhar ao carregar ou não for fornecida, o componente exibe as iniciais extraídas de label. Quando nenhuma das opções está disponível, um ícone genérico de usuário é mostrado.

Padrão

Estado padrão sem imagem nem nome — exibe o ícone genérico de usuário.

import { MkAvatar } from '@db1/makuco-ui-react';

<MkAvatar />

<mk-avatar></mk-avatar>

Com imagem

Passe uma URL para src para exibir a foto do usuário. Use alt para descrever a imagem para leitores de tela.

<MkAvatar src="https://i.pravatar.cc/150?img=5" alt="Foto de usuário" />

<mk-avatar src="https://i.pravatar.cc/150?img=5" alt="Foto de usuário"></mk-avatar>

Com iniciais

Quando src não está disponível, o componente extrai as iniciais de label. Para "João Silva", as iniciais são "JS" — primeira letra do primeiro nome e primeira letra do último nome.

<MkAvatar label="João Silva" />

<mk-avatar label="João Silva"></mk-avatar>

Tamanhos

Cinco tamanhos disponíveis via prop size: xs, sm, md (padrão), lg e xl.

<MkAvatar size="xs" label="João Silva" />
<MkAvatar size="sm" label="João Silva" />
<MkAvatar size="md" label="João Silva" />
<MkAvatar size="lg" label="João Silva" />
<MkAvatar size="xl" label="João Silva" />

<mk-avatar size="xs" label="João Silva"></mk-avatar>
<mk-avatar size="sm" label="João Silva"></mk-avatar>
<mk-avatar size="md" label="João Silva"></mk-avatar>
<mk-avatar size="lg" label="João Silva"></mk-avatar>
<mk-avatar size="xl" label="João Silva"></mk-avatar>

Formas

A prop shape controla o border-radius. circle é o padrão; square usa o token de raio padrão.

<MkAvatar shape="circle" label="João Silva" />
<MkAvatar shape="square" label="João Silva" />

<mk-avatar shape="circle" label="João Silva"></mk-avatar>
<mk-avatar shape="square" label="João Silva"></mk-avatar>

Fallback de imagem

Quando a URL em src é inválida ou a imagem falha ao carregar, o componente regride automaticamente para as iniciais (se label for fornecido) ou para o ícone genérico.

{/* Se a imagem falhar, as iniciais são exibidas */}
<MkAvatar src="https://broken.url/does-not-exist.jpg" label="João Silva" />

<!-- Se a imagem falhar, as iniciais são exibidas -->
<mk-avatar src="https://broken.url/does-not-exist.jpg" label="João Silva"></mk-avatar>

Editable

Com editable, o avatar exibe um overlay translúcido no hover com o ícone de upload. Ao clicar (ou pressionar Enter/Space via teclado), abre o seletor de arquivos nativo e emite mkAvatarUpload com o File selecionado.

O componente não realiza o upload nem exibe uma prévia imediata — o consumidor é responsável por:

Enviar o arquivo para a CDN ou Object Storage.
Atualizar a prop src com a URL definitiva.

O comportamento é idêntico independentemente de já existir uma imagem: o overlay sempre oferece a ação de substituir a foto.

import { useState } from 'react';
import { MkAvatar } from '@db1/makuco-ui-react';

function ProfileAvatar() {
  const [src, setSrc] = useState<string | undefined>(undefined);

  const handleUpload = (event: CustomEvent<{ file: File }>) => {
    const { file } = event.detail;
    // Prévia imediata com URL de objeto local
    setSrc(URL.createObjectURL(file));
    // Faça o upload para a CDN e atualize src com a URL definitiva
  };

  return (
    <MkAvatar
      src={src}
      label="João Silva"
      editable
      onMkAvatarUpload={handleUpload}
    />
  );
}

<mk-avatar
  [src]="avatarSrc"
  label="João Silva"
  editable
  (mkAvatarUpload)="onUpload($event)"
></mk-avatar>

avatarSrc: string | undefined = undefined;

onUpload(event: CustomEvent<{ file: File }>) {
  const { file } = event.detail;
  // Prévia imediata com URL de objeto local
  this.avatarSrc = URL.createObjectURL(file);
  // Faça o upload para a CDN e atualize avatarSrc com a URL definitiva
}

Use accept para restringir os tipos de arquivo aceitos pelo seletor (padrão: "image/*"):

<MkAvatar editable accept="image/png,image/jpeg" onMkAvatarUpload={handleUpload} />

<mk-avatar editable accept="image/png,image/jpeg" (mkAvatarUpload)="onUpload($event)"></mk-avatar>

Props

Prop	Tipo	Padrão	Descrição
`src`	`string`	`undefined`	URL da imagem do avatar. Quando presente, tem prioridade sobre iniciais e ícone.
`label`	`string`	`undefined`	Nome do usuário. Usado para extrair as iniciais quando a imagem não está disponível. Ex: "João Silva" → "JS".
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`	Tamanho do avatar.
`shape`	`"circle" \| "square"`	`"circle"`	Forma do avatar. `circle` = bordas completamente arredondadas; `square` = bordas com raio padrão.
`alt`	`string`	`""`	Texto alternativo para a imagem, usado por leitores de tela. Quando fornecido, sobrepõe `label` como `aria-label`.
`editable`	`boolean`	`false`	Habilita o modo de edição. No hover exibe um overlay com ícone de upload que abre o seletor de arquivos e emite `mkAvatarUpload`.
`accept`	`string`	`"image/*"`	Tipos de arquivo aceitos pelo seletor. Equivalente ao atributo `accept` do `<input type="file">`.
`locale`	`string`	—	Tag de locale BCP 47 para i18n das strings internas (ex.: `"en"`, `"es"`, `"pt-BR"`). Quando omitido, herda o `lang` do ancestral mais próximo ou `<html lang>`.

Eventos

Evento	Componente	Payload	Descrição
`mkAvatarUpload`	`mk-avatar`	`CustomEvent<{ file: File }>`	Emitido quando o usuário seleciona um arquivo no seletor. Disponível apenas quando `editable` está ativo. O consumidor é responsável pelo upload e por atualizar `src`.

Acessibilidade

O container do avatar tem role="img" e aria-label descritivo.
A prioridade do aria-label é: prop alt → prop label → texto padrão "Avatar".
A tag <img> interna tem alt="" e aria-hidden="true" para evitar duplicação de anúncio pelos leitores de tela.
O ícone e as iniciais têm aria-hidden="true" — a semântica está no container.
No modo editable, o container perde role="img" e um <button> interno assume a responsabilidade interativa. O aria-label do botão segue o padrão: "Alterar foto de {label}" (quando label está definido) ou "Alterar foto". Use a prop locale para obter o texto no idioma correto (en, es, pt-BR).
O botão é alcançável por teclado via Tab e ativável com Enter ou Space. O overlay é exibido em :focus-visible.

Avatar

On this page