Avatar
Display user profile images with intelligent fallbacks including initials and placeholder content.
Preview
Installation
npm install @native-ui-org/primitives
pnpm add @native-ui-org/primitives
yarn add @native-ui-org/primitives
bun add @native-ui-org/primitives
Overview
Avatar is a compound component for showing user profile pictures with automatic fallback handling.
| Feature | Description | Platforms |
|---|---|---|
| Avatar | Container managing loading states | iOS, Android, Web |
| AvatarImage | Profile image with error handling | iOS, Android, Web |
| AvatarFallback | Fallback content (initials, icon) | iOS, Android, Web |
Setup & Usage Guide
Avatar handles image loading states and provides fallback content automatically.
1. Install and Import
Install from npm:
npm install @native-ui-org/primitivesThen import from the package:
import {
Avatar,
AvatarImage,
AvatarFallback
} from "@native-ui-org/primitives";2. Basic Usage
Show image with fallback initials:
<Avatar>
<AvatarImage source={{ uri: 'https://example.com/avatar.jpg' }} />
<AvatarFallback>
<Text>JD</Text>
</AvatarFallback>
</Avatar>3. Fallback with Icon
Use an icon when image fails to load:
<Avatar>
<AvatarImage source={{ uri: userAvatar }} />
<AvatarFallback>
<Icon name="user" size={24} />
</AvatarFallback>
</Avatar>4. Styled Avatars
Add custom styling:
<Avatar style={styles.avatar}>
<AvatarImage
source={{ uri: user.avatarUrl }}
style={styles.image}
/>
<AvatarFallback style={styles.fallback}>
<Text style={styles.initials}>
{user.initials}
</Text>
</AvatarFallback>
</Avatar>
const styles = StyleSheet.create({
avatar: {
width: 48,
height: 48,
borderRadius: 24,
overflow: 'hidden',
},
fallback: {
backgroundColor: '#ccc',
justifyContent: 'center',
alignItems: 'center',
},
initials: {
fontSize: 18,
fontWeight: 'bold',
},
});API Reference
Avatar
Root container managing loading state.
| Prop | Type | Default | Description |
|---|---|---|---|
asChild | boolean | false | Use Slot pattern |
...props | any | — | Standard View props |
AvatarImage
Profile image with load handling.
| Prop | Type | Default | Description |
|---|---|---|---|
source | ImageSource | — | Required. Image source |
onLoad | function | — | Called when image loads |
onError | function | — | Called when image fails |
...props | any | — | Standard Image props |
AvatarFallback
Fallback content shown when image unavailable.
| Prop | Type | Default | Description |
|---|---|---|---|
delayMs | number | 0 | Delay before showing |
asChild | boolean | false | Use Slot pattern |
...props | any | — | Standard View props |
Platform Behavior
| Platform | Implementation | Characteristics |
|---|---|---|
| iOS / Android | React Native Image component | Native image caching |
| Web | HTML img with loading states | Browser image optimization |
| All Platforms | Consistent API | Same props, same behavior |
Accessibility
All Platforms:
- Images include
alttext support (web) - Proper accessibility labels
- Works with screen readers
Best practices:
- Provide meaningful fallback content
- Use appropriate
accessibilityLabel - Consider color contrast for initials
Version History
| Version | Notes |
|---|---|
0.1.0 | Initial release — avatar with image and fallback support. |
Summary: Avatar displays user profile pictures with automatic fallback handling. Use it for user profiles, comment sections, or any user-identifying UI. Provides graceful degradation when images fail to load.