Represent a person, a team or a thing with an image, initials or an icon, with an indicator on a corner or an edge, a ring and group stacking that hold at every size.
Avatars represent a person, team, brand, or object in a compact form. Use them to support recognition, ownership, and presence without taking much space.
When to use
Use Avatar when identity matters more than detail. Use Avatar.Group when several people belong to one thing: participants, assignees, reviewers, collaborators.
Show a profile image next to names, comments, cards, or messages.
Represent a person when space is limited in dense tables or lists.
Display presence inside shared work, ownership, or activity history.
Carry a small square of meaning that is not a person at all: a file, a folder, an integration, a metric. The component is a shaped, sized, fallback-aware container, so those fit it as well as a face.
Do not use when
The image is decorative and adds no meaning.
You need a detailed profile preview as the primary content.
The avatar would be the only thing identifying a critical action.
An avatar supports recognition. It should not carry essential meaning on its own. Keep a text label nearby whenever the person or entity has to be identified.
Content
Three routes, in a fixed order: src, then icon, then children. That order is also the fallback chain, so a broken image shows the icon or initials instead of a browser glyph.
Image when a real profile or brand picture exists. Always with an alt.
Initials as the fallback for a person. Keep them short: the font scales down to fit rather than clipping, so a long string shrinks until it is unreadable.
Icon for generic entities, placeholders and system objects. Use an Icon by name, so the glyph follows whichever icon pack the product installs.
Keep shape and size identical between the image and its fallback, so nothing moves when the image fails.
Color
A colorless avatar is the default and usually the right answer: it is a quiet neutral that does not compete with the name beside it. Reach for color when the fill means something.
Derive the color from something stable (a user id, a team, a file type), never from list position, or the same person changes color between screens.
filled is the readable treatment and the default when you set color alone. Prefer it.
solid puts white text on the ramp's mid tone and misses AA contrast on most warm hues. If you need solid, use a cool hue like geekblue or purple, or a neutral ramp, whose fill is darker.
Do not mix many fallback colors inside one group. The stack should read as one object, not a paint chart.
Image avatars ignore the treatment entirely, and get it back on their own if the src fails. So it is safe to set color on every row of a list whether or not the person has a photo.
Color is never the signal on its own. A red avatar does not say 'blocked' and a green one does not say 'online': that is what the indicator, the label and the tooltip are for.
Size and shape
Small in tables, compact lists and dense toolbars; medium as the default for most surfaces; large in profile headers and heroes.
Pick one shape per surface and keep it. Shape is brand, not hierarchy.
Circles for people, squares or squircles for things. That is a convention worth keeping, because it tells a reader what kind of entity a row is before they read it.
squircle renders as a plain square wherever corner-shape is unsupported, so never let it be the only difference between two meanings.
Keep every avatar in a group the same size and shape.
Size the avatar through size, not a size-* utility: only the prop scales the initials to fit.
A numeric size keeps an 18px font. Initials in a size={64} avatar stay 18px. Set style={{ fontSize }} to change it. An icon scales with the box.
The corner
indicator is the slot for anything that hangs off an avatar: a presence dot, a count, a flag, a brand glyph, a camera button. Use it rather than wrapping the avatar in a <Badge>, which centers the node on the avatar's box corner instead of on its painted edge.
Decide first whether the node is a control or a state. A control is a Button, which brings the role, the focus ring and Enter/Space with it. A state is a plain span, or a Badge when it is a count, and is not focusable.
One indicator per avatar. If you need two, you need a second line of information, not a second corner.
Keep indicatorPosition consistent across a product: presence at bottom-end, counts at top-end is the convention most people already read. Keep top-center and bottom-center for a label that names the avatar, like a live tag.
A remove affordance is not an indicator: it covers the whole avatar, because the target is the avatar.
Making one clickable
Avatar is not a control and cannot be turned into one at the call site: its props are a closed list with no role, tabIndex or aria-* to put beside an onClick. Put it inside a Button, or use Button's own avatar prop, which gets the picture and the semantics at once.
Every tap target in an avatar pattern is a Button: the account menu trigger, a story ring, a face in a picker.
A reveal-on-hover control has to reveal on focus too, or it does not exist for a keyboard.
Name the action, not only the person: “Open your account menu”, “Remove Ada Lovelace from this project”.
Groups
Use a group when the relationship between the people matters more than each full profile.
Keep it compact in dense layouts: cards, table cells, headers.
Use max to collapse the overflow into a +N chip, and let the chip reveal the rest on hover, focus or click.
Keep the order meaningful: owner first, then contributors. Do not re-sort a group in response to a hover or a view, because that moves the row under the reader's cursor.
Do not hide participants behind the overflow when the identity of every one of them affects a decision. Give that case a list.
Set size and shape on the group, not on each child. They apply to every avatar inside it.
Write max={{ count }}. The flat maxCount, maxStyle, maxPopoverPlacement and maxPopoverTrigger are deprecated and each logs a warning.
Change the overlap on the children. Setting --ant-avatar-group-overlapping on the group does nothing. Put a margin class on the children instead, like [&>*:not(:first-child)]:-ms-md.
Overlapping avatars alone do not explain membership. If the list matters, put the names in adjacent text, a tooltip, a popover, or another readable view.
Labels and context
Show the name near the avatar wherever there is room.
For a group, add a count in text (“8 members”) when the total matters.
Tooltips are extra context, never the only label. They do not exist for touch.
Keep initials predictable and derived from the displayed name, so the same person is always the same two letters.
Images
Give every image avatar an alt when it identifies someone, and an empty alt="" when the name is already in the text beside it.
Use srcSet for high density screens. An avatar is small, so a 2x source costs little and shows.
Handle onError only when you need something other than the fallback to icon or children. Return false to keep the broken image while you retry the URL.
Never leave a broken image state visible.
Do not write “avatar” or “profile picture” as alt text for a known person. Write the name.