An image element with a fallback for representing the user. Uses expo-image on native and Radix UI Avatar on web.

Installation

npm
yarn
pnpm
bun
npm install @radix-ui/react-avatar
Copy

Usage

import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar";
Copy

Examples

Basic Avatar

A simple avatar with an image and fallback initials.

Basic Avatar
EB
View Code
Copy

Fallback Only

When no image is provided or the image fails to load, the fallback is displayed.

Fallback Avatar
EB
View Code
Copy

Custom Sizes

Customize the avatar size using Tailwind classes.

Avatar Sizes
EBEBEB
View Code
Copy

Rounded Variants

Use different border radius values to customize the shape.

Avatar Shapes
EBEBEB
View Code
Copy

Avatar Group

Stack avatars together with overlapping effect. Use negative margin on subsequent avatars.

Avatar Group
CNEBER
View Code
Copy

API Reference

Avatar

The root container for the avatar.

Prop
Type
Default
Description
className
string
-
CSS classes for styling the container
children
ReactNode
-
AvatarImage and AvatarFallback components

AvatarImage

The image element inside the avatar.

Prop
Type
Default
Description
src
string
-
URL of the image to display
alt
string
-
Alternative text for the image
source
ImageSource
-
expo-image source object (native only)
className
string
-
CSS classes for styling the image
onLoad
() => void
-
Callback when image loads successfully
onError
() => void
-
Callback when image fails to load

AvatarFallback

The fallback element displayed when the image is loading or fails to load.

Prop
Type
Default
Description
className
string
-
CSS classes for styling the fallback
delayMs
number
0
Delay before showing fallback (useful to avoid flash)
children
ReactNode
-
Fallback content (typically initials or an icon)

Platform Differences

Native (iOS/Android)

  • Uses expo-image for optimized image loading with caching
  • Supports all expo-image props on AvatarImage
  • React Context used to coordinate image/fallback visibility
  • data-slot attribute has no effect

Web

  • Uses Radix UI Avatar primitives
  • Built-in image loading state management
  • data-slot attributes for styling with CSS selectors
  • Supports delayed fallback rendering

Accessibility

  • Images include alt text for screen readers
  • Fallback content provides alternative identification
  • Radix UI primitives handle ARIA attributes automatically on web