Avatar

Import

import { Avatar } from 'heroui-native';

Anatomy

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

• Avatar: Main container that manages avatar display state. Provides size and color context to child components. Supports animation configuration to control all child animations.
• Avatar.Image: Optional image component that displays the avatar image. Handles loading states and errors automatically with opacity-based 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. Supports configurable entering animations with delay support.

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>;

Animation Control

Control animations at different levels of the Avatar component.

Disable All Animations

Disable all animations including children from the root component:

<Avatar animation="disable-all">
  <Avatar.Image source={{ uri: imageUrl }} />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

Custom Image Animation

Customize the image opacity animation:

<Avatar>
  <Avatar.Image
    source={{ uri: imageUrl }}
    animation={{
      opacity: {
        value: [0.3, 1],
        timingConfig: { duration: 300 },
      },
    }}
  />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

Custom Fallback Animation

Customize the fallback entering animation:

import { FadeInDown } from 'react-native-reanimated';

<Avatar>
  <Avatar.Image source={{ uri: imageUrl }} />
  <Avatar.Fallback
    animation={{
      entering: {
        value: FadeInDown.duration(400),
      },
    }}
  >
    JD
  </Avatar.Fallback>
</Avatar>;

Disable Individual Animations

Disable animations for specific components:

<Avatar>
  <Avatar.Image source={{ uri: imageUrl }} animation={false} />
  <Avatar.Fallback animation="disabled">JD</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>
  );
}

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.

AvatarImageAnimation

Animation configuration for avatar image component. Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default animations
• object: Custom animation configuration

Note: Animation is automatically disabled when asChild={true}

Avatar.Fallback

classNames prop: ElementSlots<AvatarFallbackSlots> provides type-safe CSS classes for different parts of the fallback component. Available slots: container, text.

AvatarFallbackAnimation

Animation configuration for avatar fallback component. Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default animations
• object: Custom animation configuration

PersonIconProps

Hooks

useAvatar Hook

Hook to access Avatar primitive root context. Provides access to avatar status.

Note: The status property is particularly useful for adding a skeleton loader while the image is loading.

import { Avatar, useAvatar, Skeleton } from 'heroui-native';

function AvatarWithSkeleton() {
  return (
    <Avatar>
      <Avatar.Image source={{ uri: imageUrl }} />
      <AvatarContent />
      <Avatar.Fallback>JD</Avatar.Fallback>
    </Avatar>
  );
}

function AvatarContent() {
  const { status } = useAvatar();

  if (status === 'loading') {
    return <Skeleton className="absolute inset-0 rounded-full" />;
  }

  return null;
}

Status Values:

• 'loading': Image is currently being loaded. Use this state to show a skeleton loader.
• 'loaded': Image has successfully loaded.
• 'error': Image failed to load or source is invalid. The fallback component is automatically shown in this state.