Avatar

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O componente br-avatar é a representação visual compacta de um usuário, pessoa ou entidade no GovBR-DS. Ele exibe fotos de perfil, ícones institucionais ou iniciais textuais com suporte a múltiplos tamanhos, temas e indicador de status contextual.

Para que serve

• Identificação visual de perfil: Exibe a foto do usuário logado em barras de cabeçalho, cartões de perfil, listas de contatos ou comentários.
• Resiliência e fallback visual: Caso a imagem informada falhe ao carregar (src), o componente passa suavemente para o ícone padrão ou texto alternativo sem quebrar o leiaute.
• Indicador de status integrado: Informa estados operacionais (online, offline, ocupado, ausente) através do slot dedicado status.
• Acessibilidade: Garante descrição textual adequada através da propriedade alt, essencial para pessoas que utilizam leitores de tela.

Quando utilizar

• Utilize quando:
  • For necessário identificar a pessoa autenticada no cabeçalho ou menu da aplicação.
  • Exibir listas de contatos, autores de publicações, membros de equipe ou participantes de um fluxo colaborativo.
  • Indicar o status de disponibilidade de um usuário ou atendente no sistema.
• Evite e prefira outro componente quando:
  • For necessária uma exibição de imagem ilustrativa ampla ou promocional (prefira tags HTML <img> semânticas ou contêineres ilustrativos do design).
  • O elemento requerer interações ricas com múltiplas ações (prefira compor com br-card).

Estrutura e Slots

O br-avatar é um componente autônomo e direto:

• default: Conteúdo interno livre (quando não for utilizada imagem via prop src), permitindo inserir ícones como br-icon ou texto de iniciais.
• status: Slot posicionado para inserção de um indicador visual de status sobreposto ao avatar.

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Padrão

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

IcônicoLetraImagemStatus

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Propriedades

alt

Atributo	alt
Descrição	Texto alternativo (alt) associado à imagem do avatar. Essencial para acessibilidade. Deve descrever de forma clara e concisa o conteúdo da imagem, por exemplo: "Foto de perfil de João Silva".
Tipo	string
Valor padrão	'Foto de perfil do usuário'

bgColor

Atributo	bg-color
Descrição	Permite definir a cor de fundo do componente. Aceita os seguintes formatos de cor: - Cores nomeadas do CSS: 'red', 'blue', 'green', 'yellow', etc. - Códigos hexadecimais: '#ff0000', '#00ff00', '#0000ff', etc. - Valores RGB: 'rgb(255, 0, 0)', 'rgb(0, 255, 0)', etc. - Valores RGBA: 'rgba(255, 0, 0, 0.5)', 'rgba(0, 255, 0, 0.8)', etc. - Valores HSL: 'hsl(0, 100%, 50%)', 'hsl(120, 100%, 50%)', etc. - Valores HSLA: 'hsla(0, 100%, 50%, 0.5)', 'hsla(240, 100%, 50%, 0.7)', etc. Se não especificada, usa a cor padrão do tema.
Tipo	string
Valor padrão	'#DBE8FB'

customId

Atributo	custom-id
Descrição	Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId().
Tipo	string
Valor padrão	generateUniqueId()

density

Atributo	density
Descrição	Define a densidade visual do componente. - small: Alta densidade (componente menor, mais compacto e com menos espaçamento). - medium: Densidade intermediária, padrão recomendado para a maioria dos casos. - large: Baixa densidade (componente maior, mais espaçamento e altura). Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

disabled

Atributo	disabled
Descrição	Desabilita a interação com o componente.
Tipo	boolean
Valor padrão	false

iconic

Atributo	iconic
Descrição	Exibe a variação icônica. Quando informada, tem precedência sobre isIconic.
Tipo	boolean
Valor padrão	---

isIconic Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	is-iconic
Depreciação	Use iconic.
Descrição	Força a exibição do ícone padrão, sobrescreve outras opções (texto ou imagem). Útil para manter consistência visual ou quando se deseja um avatar neutro independente do conteúdo disponível.
Tipo	boolean
Valor padrão	false

src

Atributo	src
Descrição	URL da imagem a ser exibida no avatar do tipo 'fotográfico'. Deve ser uma URL válida que aponta para a imagem desejada.
Tipo	string
Valor padrão	''

status

Atributo	status
Descrição	Exibe um indicador de status no avatar.
Tipo	boolean
Valor padrão	false

statusBgColor

Atributo	status-bg-color
Descrição	Cor de fundo do indicador de status padrão.
Tipo	string
Valor padrão	'rgb(22, 136, 33)'

statusLabel

Atributo	status-label
Descrição	Rótulo acessível do indicador de status padrão.
Tipo	string
Valor padrão	'Status do usuário'

statusPosition

Atributo	status-position
Descrição	Posição do indicador de status sobre o avatar. Aceita top-right, bottom-right, top-left ou bottom-left. Valores inválidos usam top-right.
Tipo	"bottom-left" | "bottom-right" | "top-left" | "top-right"
Valor padrão	'top-right'

statusSize

Atributo	status-size
Descrição	Tamanho do indicador de status padrão.
Tipo	string
Valor padrão	'12px'

text

Atributo	text
Descrição	Conteúdo textual do avatar. Apenas o primeiro caractere será exibido em maiúscula.
Tipo	string
Valor padrão	''

Slots

Nome	Descrição
"status"	Conteúdo customizado para o indicador de status. Quando usado, substitui a tag padrão.

Métodos

setFocus

Descrição	Move o foco programaticamente para o avatar.
Assinatura	setFocus() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"container"	Elemento externo do avatar.
"content"	Conteúdo interno do avatar (imagem, ícone ou texto).
"status"	Indicador de status posicionado sobre o avatar.

Dependências

Depende de

• br-icon
• br-tag

Gráfico

Migração de <br-avatar> (1.x → 2.x)

Na versão 1.x, o avatar era um Vue Custom Element registrado como br-avatar. Na 2.x, o nome do elemento foi preservado, mas a API foi alinhada ao padrão dos Web Components atuais.

Propriedades

API 1.x	API 2.x	Ação na migração
—	alt	Informe o texto alternativo quando houver imagem.
density	density	Mantenha o valor compatível.
iconic	iconic	Mantenha; prefira o nome canônico atual em vez do alias legado is-iconic.
image	src	Renomeie a propriedade.
name	text	Renomeie a propriedade.

Exemplo

1.x:

<br-avatar name="Maria" image="/foto.jpg" iconic></br-avatar>

2.x:

<br-avatar text="Maria" src="/foto.jpg" iconic alt="Maria"></br-avatar>