Avatar

A user avatar with multiple sizes and initials fallback when image unavailable.

Usage#

import { Avatar } from '@backstage/ui';

<Avatar src="https://example.com/user.jpg" name="Jane Doe" />

API reference#

Prop	Type	Default	Description
src	string	-	URL of the image to display. Pass an empty string to show initials fallback. Falls back to initials if the image fails to load.
name	string	-	Name of the person. Used for generating initials fallback and accessibility label.
size	x-smallsmallmediumlargex-large	medium	Visual size. Smaller sizes show 1 initial, larger sizes show 2.
purpose	informativedecoration	informative	Accessibility behavior. Use decoration when name appears in adjacent text.
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.

Avatar also accepts all standard HTML div attributes (onClick, onMouseEnter, etc.) since it extends React.ComponentPropsWithoutRef<'div'>.

Examples#

Sizes#

Avatar sizes can be set using the size prop.

<Flex direction="column" gap="6">
  <Flex>
    <Avatar size="x-small" src="..." name="Charles de Dreuille" />
    <Avatar size="small"   src="..." name="Charles de Dreuille" />
    <Avatar size="medium"  src="..." name="Charles de Dreuille" />
    <Avatar size="large"   src="..." name="Charles de Dreuille" />
    <Avatar size="x-large" src="..." name="Charles de Dreuille" />
  </Flex>
  <Flex>
    <Avatar size="x-small" src="" name="Charles de Dreuille" />
    <Avatar size="small"   src="" name="Charles de Dreuille" />
    <Avatar size="medium"  src="" name="Charles de Dreuille" />
    <Avatar size="large"   src="" name="Charles de Dreuille" />
    <Avatar size="x-large" src="" name="Charles de Dreuille" />
  </Flex>
</Flex>

Fallback#

If the image is not available, the avatar will show the initials of the name.

<Avatar
  src="https://avatars.githubusercontent.com/u/15406AAAAAAAAA"
  name="Charles de Dreuille"
/>

The `purpose` prop#

Control how the avatar is announced to screen readers using the purpose prop.

Informative (default)Use when avatar appears alone. Announced as "Charles de Dreuille" to screen readers:

DecorationUse when avatar appears with adjacent text. Hidden from screen readers:

Charles de Dreuille

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.

bui-AvatarRoot
bui-AvatarImage
bui-AvatarFallback

Changelog#

Version 0.9.0#

Breaking Changes

Breaking Migrated Avatar component from Base UI to custom implementation with size changes:
- Base UI-specific props are no longer supported
- Size values have been updated:
  - New x-small size added (1.25rem / 20px)
  - small size unchanged (1.5rem / 24px)
  - medium size unchanged (2rem / 32px, default)
  - large size changed from 3rem to 2.5rem (40px)
  - New x-large size added (3rem / 48px) #31566
Migration Guide:
```
# Remove Base UI-specific props
- <Avatar src="..." name="..." render={...} />
+ <Avatar src="..." name="..." />

# Update large size usage to x-large for same visual size
- <Avatar src="..." name="..." size="large" />
+ <Avatar src="..." name="..." size="x-large" />
```
Added purpose prop for accessibility control ('informative' or 'decoration').

Changes

Migrated CellProfile component from Base UI Avatar to Backstage UI Avatar component. #31608
Avatar components in x-small and small sizes now display only one initial instead of two, improving readability at smaller dimensions. #31623