Avatar Component

Installation

The Avatar component is used to display user profile pictures with fallback support.

Installation Command

npx @nativecn/cli add avatar

Basic Usage

Basic Avatar

Sizes

The Avatar component comes in three predefined sizes.

Avatar Sizes

Fallback States

The Avatar component handles various fallback states gracefully.

Avatar Fallbacks

Usage Example

React Native Avatar with Error Handling

import { Avatar, AvatarImage, AvatarFallback } from '../components/ui/avatar';
import { useState } from 'react';
import { useColorScheme } from 'react-native';

export function UserAvatar({ imageUrl, username }) {
  const [isLoading, setIsLoading] = useState(true);
  const colorScheme = useColorScheme(); // 'light' or 'dark'
  const initials = username
    .split(' ')
    .map(n => n[0])
    .join('')
    .toUpperCase();
    
  return (
    <Avatar size="md" mode={colorScheme}>
      <AvatarImage
        source={imageUrl}
        alt={username}
        onLoadingStatusChange={setIsLoading}
        mode={colorScheme}
      />
      <AvatarFallback 
        delayMs={600}
        isImageLoading={isLoading}
        mode={colorScheme}
      >
        {initials}
      </AvatarFallback>
    </Avatar>
  );
}

Reference

Avatar Component Props

interface AvatarProps {
  className?: string;
  children?: React.ReactNode;
  style?: React.CSSProperties;
  size?: 'sm' | 'md' | 'lg';
  mode?: 'light' | 'dark'; // Controls light/dark appearance
}

interface AvatarImageProps {
  className?: string;
  source: string;
  alt?: string;
  onLoadingStatusChange?: (isLoading: boolean) => void;
  onError?: () => void;
  mode?: 'light' | 'dark'; // Controls light/dark appearance
}

interface AvatarFallbackProps {
  className?: string;
  delayMs?: number;
  children?: React.ReactNode;
  isImageLoading?: boolean;
  hasImageError?: boolean;
  standalone?: boolean;
  mode?: 'light' | 'dark'; // Controls light/dark appearance
}

Aspect Ratio Badge