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 br-avatar representa uma pessoa ou entidade de forma compacta: mostra uma foto, a primeira letra de um nome ou um ícone de usuário.

Como o conteúdo é escolhido

1. Com iconic, mostra sempre o ícone de usuário.
2. Com text, mostra a primeira letra do texto em maiúscula.
3. Com src, mostra a imagem. Se ela não carregar, mostra o ícone.
4. Sem nenhum deles, mostra o ícone.

<br-avatar src="/fotos/maria.jpg" alt="Foto de Maria Souza"></br-avatar>
<br-avatar text="Maria"></br-avatar>
<br-avatar iconic></br-avatar>

Para indicar disponibilidade, ative status. A cor fica em status-bg-color e o texto lido pelo leitor de tela, em status-label. Para outro indicador, use o slot status.

Quando usar

• Identificar a pessoa autenticada no cabeçalho ou no menu.
• Mostrar autores, contatos ou participantes em listas.

Quando evitar

• Imagens grandes ou ilustrativas: use <img>.

Consulte as diretrizes de design do GovBR.

Exemplo(s)

Padrão

Exemplos

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

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)

O nome do elemento continua br-avatar. Algumas propriedades mudaram de nome.

1.x	2.x	O que fazer
—	alt	Informe quando houver imagem.
density	density	Mantenha.
iconic	iconic	Mantenha. O nome is-iconic ainda funciona, mas está depreciado.
image	src	Renomeie.
name	text	Renomeie.

1.x:

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

2.x:

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