Avatar

The Avatar component displays user profile images, initials, or icons. Supports different sizes, colors, and can be grouped together in an AvatarGroup. Each text slot — initials, label, description — accepts the full Text-prop API via fallbackProps / labelProps / descriptionProps.

Source

View source code

LLM docs

LLM documentation

Package

@platform-blocks/react-ui-library

Examples

⁽⁷⁾

Properties

⁽¹⁶⁾

Playground

Basics

Illustrates loading an avatar image with a reliable initials fallback for offline scenarios.

Loading demo…

import
 
{
 
Avatar
 
}
 
from
 
'@platform-blocks/react-ui-library'
 
export
 
function
 
Demo
(
)
 
{
  
return
 
(
    
<Avatar
      
src
=
{
require
(
'../../../../assets/avatars/avatar-1.png'
)
}
      
fallback
=
"JD"
      
size
=
"xl"
    
/>
  
)
}

Sizes

Display every avatar size token with guidance on when to use each scale.

Loading demo…

import
 
{
 
Avatar
,
 
Row
 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
const
 
SIZES
 
=
 
[
'xs'
,
 
'sm'
,
 
'md'
,
 
'lg'
,
 
'xl'
,
 
'2xl'
,
 
'3xl'
]
 as 
const
;
 
export
 
function
 
Demo
(
)
 
{
  
return
 
(
    
<Row
 
align
=
"center"
 
gap
=
"lg"
 
wrap
=
"wrap"
>
      
{
SIZES
.
map
(
(
size
)
 
=>
 
(
        
<Avatar
 
key
=
{
size
}
 
size
=
{
size
}
 
fallback
=
{
size
}
 
/>
      
)
)
}
    
</Row
>
  
)
;
}

Icon

Render any <Icon> inside an avatar by passing it to the fallback prop. The icon scales with the avatar size and works alongside labels, descriptions, and status indicators.

Loading demo…

import
 
{
 
Avatar
,
 
Block
,
 
Icon
,
 
Row
,
 
Text
 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
export
 
function
 
Demo
(
)
 
{
  
return
 
(
    
<Block
>
      
<Block
>
        
<Text
 
size
=
"sm"
 
color
=
"muted"
>
          
Render
 an icon inside the avatar via the 
`fallback`
 prop
        
</Text
>
        
<Row
 
gap
=
"md"
 
align
=
"center"
>
          
<Avatar
            
fallback
=
{
<Icon
 
name
=
"user"
 
color
=
"white"
 
/>
}
            
backgroundColor
=
"#6366f1"
          
/>
          
<Avatar
            
fallback
=
{
<Icon
 
name
=
"camera"
 
color
=
"white"
 
/>
}
            
backgroundColor
=
"#10b981"
          
/>
          
<Avatar
            
fallback
=
{
<Icon
 
name
=
"bell"
 
color
=
"white"
 
/>
}
            
backgroundColor
=
"#f59e0b"
          
/>
          
<Avatar
            
fallback
=
{
<Icon
 
name
=
"settings"
 
color
=
"white"
 
/>
}
            
backgroundColor
=
"#ef4444"
          
/>
        
</Row
>
      
</Block
>
 
      
<Block
>
        
<Text
 
size
=
"sm"
 
color
=
"muted"
>
          
Scales
 with the avatar size
        
</Text
>
        
<Row
 
gap
=
"md"
 
align
=
"center"
>
          
<Avatar
            
size
=
"sm"
            
fallback
=
{
<Icon
 
name
=
"user"
 
size
=
"sm"
 
color
=
"white"
 
/>
}
            
backgroundColor
=
"#6366f1"
          
/>
          
<Avatar
            
size
=
"md"
            
fallback
=
{
<Icon
 
name
=
"user"
 
size
=
"md"
 
color
=
"white"
 
/>
}
            
backgroundColor
=
"#6366f1"
          
/>
          
<Avatar
            
size
=
"lg"
            
fallback
=
{
<Icon
 
name
=
"user"
 
size
=
"lg"
 
color
=
"white"
 
/>
}
            
backgroundColor
=
"#6366f1"
          
/>
          
<Avatar
            
size
=
"xl"
            
fallback
=
{
<Icon
 
name
=
"user"
 
size
=
"xl"
 
color
=
"white"
 
/>
}
            
backgroundColor
=
"#6366f1"
          
/>
        
</Row
>
      
</Block
>
 
      
<Block
>
        
<Text
 
size
=
"sm"
 
color
=
"muted"
>
          
Icon
 avatar with label and online status
        
</Text
>
        
<Avatar
          
fallback
=
{
<Icon
 
name
=
"user"
 
color
=
"white"
 
/>
}
          
backgroundColor
=
"#6366f1"
          
label
=
"Jane Doe"
          
description
=
"Product Designer"
          online
        
/>
      
</Block
>
    
</Block
>
  
)
;
}

Colors

Preview semantic color tokens and custom hex backgrounds applied to avatar fallbacks.

Loading demo…

import
 
{
 
Avatar
,
 
Block
 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
export
 
function
 
Demo
(
)
 
{
  
return
 
(
    
<Block
 
align
=
"flex-start"
>
     
<Avatar
        
fallback
=
"AB"
        
backgroundColor
=
"#FF6B6B"
        
label
=
"Custom Red Background"
      
/>
    
</Block
>
  
)
}

Groups

Showcases how AvatarGroup overlaps avatars by default to conserve space.

Loading demo…

import
 
{
 
Avatar
,
 
AvatarGroup
,
 
Block
,
 
Text
 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
const
 
TEAM
 
=
 
[
  
{
 id
:
 
1
,
 initials
:
 
'SJ'
,
 color
:
 
'#FF6B6B'
 
}
,
  
{
 id
:
 
2
,
 initials
:
 
'MC'
,
 color
:
 
'#4ECDC4'
 
}
,
  
{
 id
:
 
3
,
 initials
:
 
'ER'
,
 color
:
 
'#45B7D1'
 
}
,
  
{
 id
:
 
4
,
 initials
:
 
'DL'
,
 color
:
 
'#96CEB4'
 
}
,
  
{
 id
:
 
5
,
 initials
:
 
'KP'
,
 color
:
 
'#FFEAA7'
 
}
,
  
{
 id
:
 
6
,
 initials
:
 
'TW'
,
 color
:
 
'#DDA0DD'
 
}
,
  
{
 id
:
 
7
,
 initials
:
 
'AB'
,
 color
:
 
'#FFB6C1'
 
}
]
;
 
export
 
function
 
Demo
(
)
 
{
  
return
 
(
    
<Block
>
      
<Text
 
weight
=
"medium"
>
Simple
 group
</Text
>
      
<AvatarGroup
>
        
{
TEAM
.
map
(
(
{
 id
,
 initials
,
 color 
}
)
 
=>
 
(
          
<Avatar
 
key
=
{
id
}
 
fallback
=
{
initials
}
 
backgroundColor
=
{
color
}
 
size
=
"md"
 
/>
        
)
)
}
      
</AvatarGroup
>
      
<Text
 
variant
=
"small"
 
color
=
"muted"
>
        
Groups
 overlap avatars automatically to conserve space
.
      
</Text
>
    
</Block
>
  
)
;
}

Overflow

Set limit to cap visible avatars and show the remaining count. Pass surplusTooltip to reveal who's hidden on hover.

Loading demo…

import
 
{
 
Avatar
,
 
AvatarGroup
 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
const
 
TEAM
 
=
 
[
  
{
 id
:
 
1
,
 name
:
 
'Sarah Johnson'
,
 initials
:
 
'SJ'
,
 color
:
 
'#FF6B6B'
 
}
,
  
{
 id
:
 
2
,
 name
:
 
'Marcus Chen'
,
 initials
:
 
'MC'
,
 color
:
 
'#4ECDC4'
 
}
,
  
{
 id
:
 
3
,
 name
:
 
'Elena Ruiz'
,
 initials
:
 
'ER'
,
 color
:
 
'#45B7D1'
 
}
,
  
{
 id
:
 
4
,
 name
:
 
'David Lee'
,
 initials
:
 
'DL'
,
 color
:
 
'#96CEB4'
 
}
,
  
{
 id
:
 
5
,
 name
:
 
'Kira Patel'
,
 initials
:
 
'KP'
,
 color
:
 
'#FFEAA7'
 
}
,
  
{
 id
:
 
6
,
 name
:
 
'Tom Ward'
,
 initials
:
 
'TW'
,
 color
:
 
'#DDA0DD'
 
}
,
  
{
 id
:
 
7
,
 name
:
 
'Aisha Bello'
,
 initials
:
 
'AB'
,
 color
:
 
'#FFB6C1'
 
}
]
;
 
const
 
LIMIT
 
=
 
3
;
 
export
 
function
 
Demo
(
)
 
{
  
const
 hidden 
=
 
TEAM
.
slice
(
LIMIT
)
.
map
(
(
member
)
 
=>
 member
.
name
)
;
 
  
return
 
(
    
<AvatarGroup
 
limit
=
{
LIMIT
}
 
size
=
"md"
 
surplusTooltip
=
{
hidden
.
join
(
', '
)
}
>
      
{
TEAM
.
map
(
(
{
 id
,
 initials
,
 color 
}
)
 
=>
 
(
        
<Avatar
 
key
=
{
id
}
 
fallback
=
{
initials
}
 
backgroundColor
=
{
color
}
 
/>
      
)
)
}
    
</AvatarGroup
>
  
)
;
}

Status indicator

Demonstrates the online presence indicator, including custom indicatorColor overrides for alternate states.

Loading demo…

import
 
{
 
Avatar
,
 
Block
 
}
 
from
 
'@platform-blocks/react-ui-library'
;
import
 
type
 
{
 
AvatarProps
 
}
 
from
 
'@platform-blocks/react-ui-library'
;
 
type
 
StatusAvatar
 
=
 
Pick
<AvatarProps
,
 
'size'
 
|
 
'src'
 
|
 
'online'
 
|
 
'indicatorColor'
>
 
&
 
{
  key
:
 
string
;
  label
:
 
string
;
  description
:
 
string
;
}
;
 
const
 STATUS_AVATARS
:
 
StatusAvatar
[
]
 
=
 
[
  
{
    key
:
 
'online'
,
    label
:
 
'Josh'
,
    description
:
 
'Online'
,
    src
:
 
require
(
'../../../../assets/avatars/avatar-1.png'
)
  
}
,
  
{
    key
:
 
'available'
,
    label
:
 
'Alice'
,
    description
:
 
'Available'
,
    src
:
 
require
(
'../../../../assets/avatars/avatar-2.png'
)
  
}
,
  
{
    key
:
 
'focus'
,
    label
:
 
'Mike'
,
    description
:
 
'Focus time'
,
    src
:
 
require
(
'../../../../assets/avatars/avatar-3.png'
)
,
    indicatorColor
:
 
'#f59e0b'
  
}
,
  
{
    key
:
 
'offline'
,
    label
:
 
'Tori'
,
    description
:
 
'Last active 5m ago'
,
    src
:
 
require
(
'../../../../assets/avatars/avatar-4.png'
)
,
    online
:
 
false
  
}
]
;
 
export
 
function
 
Demo
(
)
 
{
  
return
 
(
    
<Block
 
direction
=
"row"
 
justify
=
"space-evenly"
 fullWidth
>
      
{
STATUS_AVATARS
.
map
(
(
{
 key
,
 indicatorColor
,
 online 
=
 
true
,
 
.
.
.
avatar 
}
)
 
=>
 
(
        
<Avatar
          
key
=
{
key
}
          
{
.
.
.
avatar
}
          
fallback
=
{
avatar
.
label
.
slice
(
0
,
 
2
)
.
toUpperCase
(
)
}
          
online
=
{
online
}
          
indicatorColor
=
{
indicatorColor
}
        
/>
      
)
)
}
    
</Block
>
  
)
;
}

Scan to open this page on your phonereact-ui-library.com/components/Avatar

</>

react-ui-library

100+ accessible, themeable components that work seamlessly across iOS, Android, and Web.

A Platform Blocks product.

Quick Links

Components Charts Hooks

Docs

Getting Started Localization llms.txt

Resources

FAQ Changelog Accessibility Sitemap