@umituz/react-native-avatar

User avatar components for React Native apps - image, initials, icon support, status indicators, avatar groups.

Features

• ✅ Image Avatars - Display user profile images with fallback
• ✅ Initials Generation - Automatic initials from names (Turkish character support)
• ✅ Icon Placeholders - Fallback to icons when no image/name
• ✅ Status Indicators - Online/offline/away/busy status badges
• ✅ Avatar Groups - Stacked layout with overflow count (+N)
• ✅ Consistent Colors - Same name always gets same color
• ✅ Multiple Sizes - xs, sm, md, lg, xl, xxl
• ✅ Multiple Shapes - Circle, square, rounded
• ✅ Type-Safe - Full TypeScript support

Installation

npm install @umituz/react-native-avatar

Peer Dependencies

npm install @umituz/react-native-design-system @umituz/react-native-design-system-theme

Usage

Basic Avatar

import { Avatar } from '@umituz/react-native-avatar';

// Image avatar
<Avatar
  uri="https://example.com/avatar.jpg"
  name="Ümit Uz"
  size="lg"
  shape="circle"
/>

// Initials avatar (no image)
<Avatar name="Ümit Uz" size="md" />
// Shows: ÜU

// Icon avatar (fallback)
<Avatar size="sm" />

Avatar with Status

<Avatar
  name="John Doe"
  showStatus
  status="online"
  size="md"
/>

Avatar Group

import { AvatarGroup } from '@umituz/react-native-avatar';

const users = [
  { name: 'Ümit Uz', uri: 'https://...' },
  { name: 'John Doe', uri: 'https://...' },
  { name: 'Jane Smith' },
  { name: 'Bob Johnson' },
  { name: 'Alice Brown' },
];

// Show 3 avatars + overflow
<AvatarGroup items={users} maxVisible={3} />
// Shows: [Avatar] [Avatar] [Avatar] [+2]

Avatar Utilities

import { AvatarUtils, AVATAR_COLORS } from '@umituz/react-native-avatar';

// Generate initials
const initials = AvatarUtils.generateInitials('Ümit Uz'); // ÜU
const emailInitials = AvatarUtils.generateInitialsFromEmail('[email protected]'); // UE

// Get consistent color
const color = AvatarUtils.getColorForName('Ümit Uz'); // Always same color

// Get size config
const config = AvatarUtils.getSizeConfig('lg');
// Returns: { size: 56, fontSize: 18, iconSize: 28, statusSize: 12, borderWidth: 2 }

useAvatar Hook

import { useAvatar } from '@umituz/react-native-avatar';

const { isLoading, hasError, onLoad, onError, generateInitials } = useAvatar();

<Image
  source={{ uri }}
  onLoad={onLoad}
  onError={onError}
/>

{hasError && <Text>{generateInitials(name)}</Text>}

API Reference

Avatar

Avatar component with automatic fallback hierarchy.

Props:

• uri?: string - Image URI
• name?: string - User name for initials
• icon?: string - Icon name (fallback)
• size?: AvatarSize - Size preset (default: 'md')
• shape?: AvatarShape - Shape (default: 'circle')
• backgroundColor?: string - Custom background color
• showStatus?: boolean - Show status indicator
• status?: 'online' | 'offline' | 'away' | 'busy' - Status
• style?: ViewStyle - Custom container style
• imageStyle?: ImageStyle - Custom image style
• onPress?: () => void - OnPress handler

Fallback Hierarchy:

1. Image (if uri provided)
2. Initials (if name provided)
3. Icon (fallback)

AvatarGroup

Avatar group component with overflow count.

Props:

• items: AvatarGroupItem[] - Array of avatar items
• maxVisible?: number - Maximum visible avatars (default: 3)
• size?: AvatarSize - Avatar size (default: 'md')
• shape?: AvatarShape - Avatar shape (default: 'circle')
• spacing?: number - Spacing between avatars (default: -8 for overlap)
• style?: ViewStyle - Custom container style

useAvatar()

React hook for avatar state management.

Returns:

• isLoading: boolean - Image loading state
• hasError: boolean - Image error state
• onLoad: () => void - Handle image load success
• onError: () => void - Handle image load error
• reset: () => void - Reset state
• generateInitials: (name: string) => string - Generate initials
• getColorForName: (name: string) => string - Get consistent color

AvatarUtils

Utility class for avatar operations.

Methods:

• generateInitials(name: string): string - Generate initials from name
• generateInitialsFromEmail(email: string): string - Generate initials from email
• getColorForName(name: string): string - Get consistent color for name
• getSizeConfig(size: AvatarSize): SizeConfig - Get size configuration
• getBorderRadius(shape: AvatarShape, size: number): number - Get border radius
• getStatusColor(status: 'online' | 'offline' | 'away' | 'busy'): string - Get status color
• validateConfig(config: Partial<AvatarConfig>): AvatarConfig - Validate config
• hasImage(config: AvatarConfig): boolean - Check if has image
• hasInitials(config: AvatarConfig): boolean - Check if has initials
• hasIcon(config: AvatarConfig): boolean - Check if has icon

Types

• AvatarSize - 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'
• AvatarShape - 'circle' | 'square' | 'rounded'
• AvatarType - 'image' | 'initials' | 'icon'
• AvatarConfig - Avatar configuration interface
• SizeConfig - Size configuration interface
• AvatarGroupConfig - Avatar group configuration interface
• AvatarGroupItem - Avatar item for group

Constants

• SIZE_CONFIGS - Size configurations for all sizes
• AVATAR_COLORS - Array of 10 vibrant colors for avatars
• STATUS_COLORS - Status indicator colors
• SHAPE_CONFIGS - Border radius configurations
• AVATAR_CONSTANTS - Default values and constants

Size Presets

• xs - 24px (fontSize: 10, iconSize: 12, statusSize: 6)
• sm - 32px (fontSize: 12, iconSize: 16, statusSize: 8)
• md - 40px (fontSize: 14, iconSize: 20, statusSize: 10) - Default
• lg - 56px (fontSize: 18, iconSize: 28, statusSize: 12)
• xl - 80px (fontSize: 24, iconSize: 40, statusSize: 16)
• xxl - 120px (fontSize: 36, iconSize: 60, statusSize: 20)

Turkish Character Support

The package fully supports Turkish characters in initials generation:

AvatarUtils.generateInitials('Ümit Uz'); // ÜU
AvatarUtils.generateInitials('Şahin Yılmaz'); // ŞY
AvatarUtils.generateInitials('Özgür Çelik'); // ÖÇ

License

MIT

Author

Ümit UZ [email protected]