avatar

Imported from financialvice/realtime-rrweb-recording (packages/ui/src/native-mobile/avatar/AGENTS.md). Install upstream with npx skills add financialvice/realtime-rrweb-recording --skill avatar. Copyright stays with the author.

Avatar

Displays a user avatar with support for images, text initials, or fallback icons.

Imports

Note: Before importing this component, ensure you have completed the setup as per the Quick Start guide.

import { Avatar } from 'heroui-native';

Usage

Basic Usage

The Avatar component displays a default person icon when no image or text is provided.

<Avatar>
  <Avatar.Fallback />
</Avatar>

With Image

Display an avatar image with automatic fallback handling.

<Avatar>
  <Avatar.Image source={{ uri: 'https://example.com/avatar.jpg' }} />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

With Text Initials

Show text initials as the avatar content.

<Avatar>
  <Avatar.Fallback>AB</Avatar.Fallback>
</Avatar>

With Custom Icon

Provide a custom icon as fallback content.

<Avatar>
  <Avatar.Fallback>
    <Ionicons name="person" size={18} />
  </Avatar.Fallback>
</Avatar>

Sizes

Control the avatar size with the size prop.

<Avatar size="sm">
  <Avatar.Fallback />
</Avatar>

<Avatar size="md">
  <Avatar.Fallback />
</Avatar>

<Avatar size="lg">
  <Avatar.Fallback />
</Avatar>

Variants

Choose between different visual styles with the variant prop.

<Avatar variant="default">
  <Avatar.Fallback>DF</Avatar.Fallback>
</Avatar>

<Avatar variant="soft">
  <Avatar.Fallback>SF</Avatar.Fallback>
</Avatar>

Colors

Apply different color variants to the avatar.

<Avatar color="default">
  <Avatar.Fallback>DF</Avatar.Fallback>
</Avatar>

<Avatar color="accent">
  <Avatar.Fallback>AC</Avatar.Fallback>
</Avatar>

<Avatar color="success">
  <Avatar.Fallback>SC</Avatar.Fallback>
</Avatar>

<Avatar color="warning">
  <Avatar.Fallback>WR</Avatar.Fallback>
</Avatar>

<Avatar color="danger">
  <Avatar.Fallback>DG</Avatar.Fallback>
</Avatar>

Delayed Fallback

Show fallback after a delay to prevent flashing during image load.

<Avatar>
  <Avatar.Image source={{ uri: imageUrl }} />
  <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
</Avatar>

Custom Image Component

Use a custom image component with the asChild prop.

import { Image } from 'expo-image';

<Avatar>
  <Avatar.Image source={{ uri: imageUrl }} asChild>
    <Image style={{ width: '100%', height: '100%' }} contentFit="cover" />
  </Avatar.Image>
  <Avatar.Fallback>EI</Avatar.Fallback>
</Avatar>;

Example

import { Avatar } from 'heroui-native';
import { View } from 'react-native';

export default function AvatarExample() {
  const users = [
    { id: 1, image: 'https://example.com/user1.jpg', name: 'John Doe' },
    { id: 2, image: 'https://example.com/user2.jpg', name: 'Jane Smith' },
    { id: 3, image: 'https://example.com/user3.jpg', name: 'Bob Johnson' },
  ];

  return (
    <View className="flex-row gap-4">
      {users.map((user) => (
        <Avatar key={user.id} size="lg" color="accent">
          <Avatar.Image source={{ uri: user.image }} />
          <Avatar.Fallback>
            {user.name
              .split(' ')
              .map((n) => n[0])
              .join('')}
          </Avatar.Fallback>
        </Avatar>
      ))}
    </View>
  );
}

Anatomy

<Avatar>
  <Avatar.Image />
  <Avatar.Fallback />
</Avatar>

• Avatar: Main container that manages avatar display state. Provides size and color context to child components.
• Avatar.Image: Optional image component that displays the avatar image. Handles loading states and errors automatically with fade-in animation.
• Avatar.Fallback: Optional fallback component shown when image fails to load or is unavailable. Displays a default person icon when no children are provided.

API Reference

Avatar

Avatar.Image

Props extend different base types depending on the asChild prop value:

• When asChild={false} (default): extends AnimatedProps<ImageProps> from React Native Reanimated
• When asChild={true}: extends primitive image props for custom image components

Note: When using asChild={true} with custom image components, the className prop may not be applied in some cases depending on the custom component's implementation. Ensure your custom component properly handles style props.

Avatar.Fallback

PersonIconProps