Avatar

An avatar component with a fallback for initials.

Usage#

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

<Avatar
  src="https://avatars.githubusercontent.com/u/1540635?v=4"
  name="Charles de Dreuille"
/>

API reference#

Prop	Type	Default	Responsive
src	string	-	No
name	string	-	No
size	x-smallsmallmediumlargex-large	medium	Yes
purpose	informativedecoration	informative	No
className	string	-	No
style	CSSProperties	-	No

Examples#

Sizes#

Avatar sizes can be set using the size prop.

<Flex gap="4" direction="column">
  <Avatar
    src="https://avatars.githubusercontent.com/u/1540635?v=4"
    name="Charles de Dreuille" size="x-small"
  />
  <Avatar
    src="https://avatars.githubusercontent.com/u/1540635?v=4"
    name="Charles de Dreuille" size="small"
  />
  <Avatar
    src="https://avatars.githubusercontent.com/u/1540635?v=4"
    name="Charles de Dreuille" size="medium"
  />
  <Avatar
    src="https://avatars.githubusercontent.com/u/1540635?v=4"
    name="Charles de Dreuille" size="large"
  />
  <Avatar
    src="https://avatars.githubusercontent.com/u/1540635?v=4"
    name="Charles de Dreuille" size="x-large"
  />
</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 name appears adjacent to avatar. Hidden from screen readers to avoid redundancy:

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-AvatarRoot[data-size="small"]
bui-AvatarRoot[data-size="medium"]
bui-AvatarRoot[data-size="large"]
bui-AvatarImage
bui-AvatarFallback

Changelog#

0.9.0 - 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)

Migration:

# 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'). #31566

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