Skip to main content

ā€‹
Installation

npx @soft-ui/cli add avatar

ā€‹
Usage

import { Avatar } from '@soft-ui/react/avatar'

export default function Example() {
  return (
    <Avatar 
      src="/avatars/user.jpg" 
      alt="User name"
      initials="JD"
    />
  )
}

ā€‹
Examples

ā€‹
Sizes

Avatars support six sizes from 3xs to l. 
<Avatar size="3xs" initials="JD" />
<Avatar size="2xs" initials="JD" />
<Avatar size="xs" initials="JD" />
<Avatar size="s" initials="JD" />
<Avatar size="m" initials="JD" />
<Avatar size="l" initials="JD" />

ā€‹
Shapes

Choose between circular (default) and square shapes. 
<Avatar shape="circular" src="/avatar.jpg" />
<Avatar shape="square" src="/avatar.jpg" />

ā€‹
Image with Fallback

When an image fails to load, avatar shows initials or icon fallback. 
// Shows image if src loads, otherwise shows initials
<Avatar 
  src="/avatar.jpg" 
  initials="JD" 
  alt="John Doe"
/>

// Use icon fallback instead
<Avatar 
  src="/avatar.jpg"
  fallback="icon"
/>

ā€‹
Initials

Display up to 2 characters as initials (automatically uppercased). 
<Avatar initials="JD" />
<Avatar initials="AB" />
<Avatar initials="XY" />

ā€‹
Custom Icon

Provide a custom icon for the fallback. 
import { RiTeamLine } from '@soft-ui/icons'

<Avatar icon={<RiTeamLine />} />

ā€‹
Decorative Colors

Use with isEmphasized to apply decorative background colors. 
<Avatar initials="JD" isEmphasized color="blue" />
<Avatar initials="AS" isEmphasized color="purple" />
<Avatar initials="MK" isEmphasized color="pink" />
<Avatar initials="TW" isEmphasized color="green" />

ā€‹
Avatar Group

Display multiple overlapping avatars with overflow count. 
import { AvatarGroup } from '@soft-ui/react/avatar-group'

<AvatarGroup max={3} size="m">
  <Avatar src="/avatars/1.jpg" initials="JD" />
  <Avatar src="/avatars/2.jpg" initials="AS" />
  <Avatar src="/avatars/3.jpg" initials="MK" />
  <Avatar src="/avatars/4.jpg" initials="TW" />
  <Avatar src="/avatars/5.jpg" initials="LB" />
</AvatarGroup>
// Shows first 3 avatars + "+2" overflow indicator

ā€‹
API Reference

ā€‹
Avatar

ā€‹
size
string
default:"m"
Size of the avatar: 3xs, 2xs, xs, s, m, l.
ā€‹
shape
string
default:"circular"
Shape of the avatar: circular, square.
ā€‹
src
string
Image source URL.
ā€‹
alt
string
default:""
Alt text for the image.
ā€‹
initials
string
1-2 characters to display as fallback. Automatically uppercased and limited to 2 characters.
ā€‹
icon
ReactNode
Custom icon element for fallback. Defaults to user icon.
ā€‹
fallback
string
default:"icon"
Fallback type to display when image fails: initials, icon.
ā€‹
isEmphasized
boolean
default:false
When true, applies border and allows color customization.
ā€‹
color
string
Decorative color (requires isEmphasized): red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.
ā€‹
unsafeClassName
string
Explicit escape hatch for intentional structural overrides.

ā€‹
AvatarGroup

ā€‹
size
string
default:"m"
Size applied to all child avatars: 3xs, 2xs, xs, s, m, l.
ā€‹
max
number
default:4
Maximum number of avatars to display. Additional avatars show as ā€œ+Nā€ overflow count.
ā€‹
children
ReactNode
Avatar components to group.
ā€‹
unsafeClassName
string
Explicit escape hatch for intentional structural overrides.

ā€‹
Accessibility

  • Always provide alt text for images
  • Initials are visible to screen readers
  • Fallback icons use aria-hidden when initials/images are present
  • Use semantic color variants for status indicators when possible

ā€‹
Design Tokens

Avatar uses design tokens for consistent styling:
  • Spacing: --space-* for sizes
  • Border radius: --radius-8 (square), --radius-max (circular)
  • Colors: --color-utility-avatar, --color-surface-decorative-*, --color-border-decorative-*
  • Typography: --font-size-*, --line-height-*, --font-weight-medium

Build docs developers (and LLMs) love

Get started for freeTalk to us