Primitivedata-display

Avatar

Stable

Moldura circular para retrato, com fallback de iniciais, badge de status, agrupamento e contagem. Composto sobre Base UI Avatar. Quase tudo o que dá errado num avatar dá errado na árvore de acessibilidade e não na tela: iniciais lidas em voz alta são letras, não uma pessoa — por isso o fallback aceita `label`, que esconde as iniciais e anuncia o nome no lugar delas.

Instalação

npx up-web-ds add avatar

Preview

Default

Fallback

Sizes

With Badge

Walter Souza · online

Group

UWUWUW

All states

Default

Fallback

Sizes

With Badge

Walter Souza · online

Group

UWUWUW

Usage

@/components/ui/avatar

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

Avatar

1
2
3
4<Avatar>
  <AvatarImage src={portrait('#5c6b73')} alt="Walter Souza" />
  <AvatarFallback label="Walter Souza">WS</AvatarFallback>
</Avatar>

Props

Avatar

Props de Avatar
Prop	Type	Default	Description
size	`"default" \| "sm" \| "lg"`	`'default'`
className	`string \| ((state: AvatarRootState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, AvatarRootState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: AvatarRootState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende AvatarPrimitive.Root.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

AvatarImage

Props de AvatarImage
Prop	Type	Default	Description
className	`string \| ((state: AvatarImageState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
onLoadingStatusChange	`((status: ImageLoadingStatus) => void)`	sem valor padrão	Callback fired when the loading status changes.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<React.DetailedHTMLProps<React.ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, AvatarImageState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: AvatarImageState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende AvatarPrimitive.Image.Props. Aceita também os atributos padrão de um elemento React (287 não listados).

AvatarFallback

Props de AvatarFallback
Prop	Type	Default	Description
label	`string`	sem valor padrão
className	`string \| ((state: AvatarFallbackState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
delay	`number`	`0`	How long to wait before showing the fallback. Specified in milliseconds.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, AvatarFallbackState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	`React.CSSProperties \| ((state: AvatarFallbackState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.

Estende AvatarPrimitive.Fallback.Props. Aceita também os atributos padrão de um elemento React (275 não listados).

AvatarBadge

Estende React.ComponentProps<'span'>. Aceita também os atributos padrão de um elemento React (280 não listados).

AvatarGroup

Estende React.ComponentProps<'div'>. Aceita também os atributos padrão de um elemento React (280 não listados).

AvatarGroupCount

Estende React.ComponentProps<'div'>. Aceita também os atributos padrão de um elemento React (280 não listados).

Composition

AvatarImage e AvatarFallback são alternativas dentro do mesmo Avatar: o fallback é o que sobra quando a imagem não carrega, e não um irmão opcional.

Composição de Avatar

Avatar

AvatarImage
AvatarFallback
AvatarBadge

Metadata

Notas de acessibilidade

Não é interativo por si: não entra na sequência de tabulação e não anima, então teclado e movimento não têm superfície onde falhar — quando um avatar vira gatilho, quem carrega foco e alvo é o controle que o envolve. Leitor de tela verificado por teste: com imagem o nome vem do alt, que diz quem é e não o que é o arquivo; sem imagem, `label` esconde as iniciais e anuncia a pessoa, de modo que o mesmo avatar anuncia o mesmo nome tenha a foto carregado ou não; um grupo fala uma vez em vez de uma vez por rosto; e o badge de status fica fora da árvore, porque um ponto colorido não diz nada — o significado dele vive no texto ao lado. Contraste verificado nos dois temas: o aro da moldura é desenhado em pseudo-elemento com mix-blend, então ele lê como hairline sobre retratos claros e escuros em vez de sumir nos claros.

Classificação

Layer: Primitive
Domínio: Domain-free (compartilhado)
Categoria: data-display
Status: Stable

Origem e distribuição

Fonte: shadcn registry / avatar
Licença: MIT
URL: https://ui.shadcn.com/r/styles/base-vega/avatar.json
Distribuição: Interna

Acessibilidade

Teclado: revisado
Leitor de tela: revisado
Touch: revisado
Reduced motion: revisado

Dependências

Pacotes: @base-ui/react
Ícones: Nenhum
Construído sobre: Nenhum
Usado por: Nenhum ainda