Skip to main content
The Avatar component displays user profile images with built-in fallback support and customizable styling. Use AvatarGroup to show multiple avatars with overflow handling.

​
Basic usage

import { Avatar } from '@raystack/apsara';

function UserProfile() {
  return (
    <Avatar
      src="https://images.unsplash.com/photo-1511485977113-f34c92461ad9"
      alt="John Doe"
      fallback="JD"
    />
  );
}

​
With fallback text

When the image fails to load or no src is provided, the fallback is displayed. 
import { Avatar } from '@raystack/apsara';

function InitialsAvatar() {
  return (
    <Avatar 
      fallback="JD" 
      color="indigo"
      variant="soft"
    />
  );
}

​
Sizes

Avatar supports 13 size variants from 1 to 13. 
import { Avatar } from '@raystack/apsara';

function AvatarSizes() {
  return (
    <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
      <Avatar size={1} fallback="1" />
      <Avatar size={3} fallback="3" />
      <Avatar size={5} fallback="5" />
      <Avatar size={7} fallback="7" />
      <Avatar size={9} fallback="9" />
    </div>
  );
}

​
Colors

Choose from 13 color variants. 
import { Avatar } from '@raystack/apsara';

function ColoredAvatars() {
  return (
    <div style={{ display: 'flex', gap: '8px' }}>
      <Avatar fallback="IN" color="indigo" />
      <Avatar fallback="OR" color="orange" />
      <Avatar fallback="MI" color="mint" />
      <Avatar fallback="SK" color="sky" />
      <Avatar fallback="PU" color="purple" />
    </div>
  );
}

​
Variants

Avatar supports solid and soft variants. 
import { Avatar } from '@raystack/apsara';

function AvatarVariants() {
  return (
    <div style={{ display: 'flex', gap: '8px' }}>
      <Avatar fallback="SO" variant="solid" color="indigo" />
      <Avatar fallback="SF" variant="soft" color="indigo" />
    </div>
  );
}

​
Border radius

Control the border radius with the radius prop. 
import { Avatar } from '@raystack/apsara';

function AvatarRadius() {
  return (
    <div style={{ display: 'flex', gap: '8px' }}>
      <Avatar fallback="SM" radius="small" />
      <Avatar fallback="FL" radius="full" />
    </div>
  );
}

​
Avatar group

Display multiple avatars with automatic overflow handling. 
import { Avatar, AvatarGroup } from '@raystack/apsara';

function TeamAvatars() {
  return (
    <AvatarGroup max={3}>
      <Avatar fallback="JD" color="indigo" />
      <Avatar fallback="JS" color="orange" />
      <Avatar fallback="BW" color="mint" />
      <Avatar fallback="AM" color="sky" />
      <Avatar fallback="KL" color="purple" />
    </AvatarGroup>
  );
}
The example above will show the first 3 avatars and display “+2” for the remaining count.

​
Automatic color selection

Use the getAvatarColor utility to generate consistent colors based on a string. 
import { Avatar, getAvatarColor } from '@raystack/apsara';

function DynamicAvatar({ email, name }: { email: string; name: string }) {
  const color = getAvatarColor(email);
  const initials = name.split(' ').map(n => n[0]).join('').toUpperCase();
  
  return (
    <Avatar 
      fallback={initials} 
      color={color}
    />
  );
}

​
API reference

​
Avatar

​
src
string
Image source URL.
​
alt
string
Alternative text for the image.
​
fallback
ReactNode
Content to display when the image fails to load or is not provided.
​
size
1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13
default:"3"
Size of the avatar.
​
radius
'small' | 'full'
default:"'small'"
Border radius of the avatar.
​
variant
'solid' | 'soft'
default:"'soft'"
Visual style variant.
​
color
'indigo' | 'orange' | 'mint' | 'neutral' | 'sky' | 'lime' | 'grass' | 'cyan' | 'iris' | 'purple' | 'pink' | 'crimson' | 'gold'
default:"'indigo'"
Color theme for the avatar fallback.
​
className
string
Additional CSS classes to apply.
​
disabled
boolean
Whether the avatar should appear disabled.

​
AvatarGroup

​
children
React.ReactElement<AvatarProps>[]
required
Array of Avatar components to display.
​
max
number
Maximum number of avatars to display before showing overflow count.
​
className
string
Additional CSS classes to apply to the group container.

​
getAvatarColor

Utility function to generate a consistent color based on a string input.
​
str
string
required
Input string (e.g., email or username) to generate color from.