Avatar
A visual representation of a person or company, helping users quickly recognise entities within a list or group.
Accessibility
Avatar is decorative by default, hidden from assistive technologies. An aria-label may be provided where more meaningful context is needed, or required when interactive.Choosing a treatment
Match the treatment to the identity data you have.Image
The most recognisable treatment. When a photo or company logo is available, pass it as imageUrl. This is the strongest treatment and should be preferred over initials whenever you can show a current image.Provide an image at least twice the box size so it stays sharp. Omit imageUrl when the image must not be shown — for example when names are hidden.If the image fails to load, IconImageBroken is shown instead of silently falling back to initials. That makes a broken image obvious so it can be fixed.Photo
Unavailable
Initials
When there is a name but no image, Avatar shows the first letter of name. The background colour is derived from that name so the same identity stays consistent wherever they appear.Language
The first letter of name works across scripts such as Latin, Thai and Chinese, with no extra configuration. Numbers, punctuation and symbols are skipped. If no letter is found, the empty treatment is used instead.Thai
Chinese
Company icon
For an organisation with no logo and no name, you may provide an icon, typically IconCompany. Note that passing name and icon together shows initials, not the icon.Empty
When there is no identity yet, omit name to show IconProfile.To let someone add a photo, treat the empty avatar as a control. See As a control.Fallback order
- While loading, a skeleton is shown.
- Otherwise a loaded imageUrl is shown. If the URL fails, IconImageBroken is shown (not initials or icon).
- When no image is provided, the first letter of name is shown.
- When no image or name is provided, an icon is shown.
- When nothing is provided, IconProfile is shown.
Size
Tailor the size to the surrounding layout with the size prop. Use smaller sizes in dense lists and larger sizes in profile headers. When no size is specified, the avatar appears at standard. Size is a fixed value, not a responsive prop — pick a size per breakpoint with layout rather than scaling the box.Contextual design
Avatar always has a surface-coloured ring so it stays distinct when overlapping or sitting on a coloured background. If you need a coloured ring, wrap Avatar in a Box and keep that radius in sync with the Avatar size.Composition patterns
Pairing with text
Pair Avatar with visible text so the name is available to everyone. The easiest way is Columns or Inline, with the Avatar sized to its content and aligned to the text.Leia OrganaProduct Designer
Tooltip
When the avatar is the only identifier, wrap Avatar with TooltipRenderer so the name is available on hover and focus. Spread triggerProps last onto Avatar, and pass aria-label because those props make the avatar focusable.Skip a tooltip when the name is already visible beside the avatar. If click opens a MenuRenderer, put the tooltip on the menu trigger, not on Avatar inside it.As a control
Use onClick only when the square itself is the control, such as adding or updating a photo. Provide an icon, aria-label and omit name.Do not add onClick when a parent is already the button — for example a row that opens a profile, or a MenuRenderer trigger. In those cases the avatar should stay decorative.Loading
While identity data is being fetched, set loading to show a skeleton in place of the photo, initials, or icon. This state is not announced. If the avatar is also a control, it remains clickable so someone can add or update a photo before the current image arrives.General best practice
- Avatar does not need a visible label. Pair it with a name when that helps people scan a list or card.
- If the Avatar is the only identifier, pass aria-label — and consider a tooltip.
- Use a current photo or company logo when you have one, otherwise initials from the name. For an unnamed organisation, pass icon.
- To show status, compose Badge on the wrapper.
- Do not add onClick when a parent is already the button.
When to use
Use an Avatar:
- to represent a person or company using a photo, initials, or icon, at various sizes
- to help users quickly recognise entities within a list or group
- as a control that lets users add or update their Avatar photo.
Don’t use an Avatar:
- for company logos on job listing cards (use their existing components)
- as the only identifier, unless you pass aria-label
Data attributes
Braid components are very explicit about the properties they accept, which makes providing arbitrary data attributes not possible. Instead, a data prop can be provided as a single collection of data attributes.<Avatar name="Leia Organa" data={{ testid: 'avatar-1' }} // => data-testid="avatar-1" />
Alternatives
- IconProfile — For a profile icon that is not an avatar.
- IconCompany — For a company mark without an Avatar frame.
- Badge — For communicating the status of an object.
- TooltipRenderer — To provide non-critical, extra context on mouse hover or keyboard focus.
- MenuRenderer — For custom menu triggers where standard components like OverflowMenu aren't suitable.
On this page