Avatar
A flexible avatar component for displaying user profile images with fallback support.
Installation
Install the component:
npx natively-ui add avatarUsage
AvatarDemo.jsx
1import Avatar from '@/components/ui/avatar';
2
3export default function MyComponent() {
4 return (
5 <Avatar
6 src="https://example.com/user-avatar.jpg"
7 alt="John Doe"
8 size="default"
9 variant="circle"
10 />
11 );
12}Props
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | null | - | The source URL of the avatar image. |
| alt | string | "" | Alternative text for the image, used for accessibility and generating initials. |
| fallback | string | - | Custom fallback text to display when image fails to load. |
| size | 'sm' | 'default' | 'lg' | 'xl' | 'default' | The size of the avatar. |
| variant | 'circle' | 'rounded' | 'square' | 'circle' | The shape variant of the avatar. |
| className | string | "" | Additional CSS classes for the avatar container. |
| fallbackClassName | string | "" | Additional CSS classes for the fallback text. |
Features
- Multiple size options (sm, default, lg, xl)
- Three shape variants (circle, rounded, square)
- Automatic fallback to initials when image fails to load
- Smart initial generation from alt text or fallback prop
- Error handling for broken image URLs
- Customizable styling with className props
- Accessibility support with alt text
- Built with Tailwind CSS and React Native
Examples
Basic Usage
AvatarDemo.jsx
1<Avatar
2 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
3 alt="John Doe"
4/>Sizes
AvatarDemo.jsx
1<View style={{ flexDirection: 'row', gap: 12, alignItems: 'center' }}>
2 <Avatar
3 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
4 alt="Small Avatar"
5 size="sm"
6 />
7 <Avatar
8 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
9 alt="Default Avatar"
10 size="default"
11 />
12 <Avatar
13 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
14 alt="Large Avatar"
15 size="lg"
16 />
17 <Avatar
18 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
19 alt="Extra Large Avatar"
20 size="xl"
21 />
22</View>Shape Variants
AvatarDemo.jsx
1<View style={{ flexDirection: 'row', gap: 16, alignItems: 'center' }}>
2 <Avatar
3 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
4 alt="Circle Avatar"
5 variant="circle"
6 size="lg"
7 />
8 <Avatar
9 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
10 alt="Rounded Avatar"
11 variant="rounded"
12 size="lg"
13 />
14 <Avatar
15 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
16 alt="Square Avatar"
17 variant="square"
18 size="lg"
19 />
20</View>Fallback Initials
AvatarDemo.jsx
1<View style={{ flexDirection: 'row', gap: 12, alignItems: 'center' }}>
2 {/* Will show "JD" initials */}
3 <Avatar
4 alt="John Doe"
5 size="lg"
6 />
7
8 {/* Will show "AB" initials */}
9 <Avatar
10 alt="Alice Smith"
11 fallback="AB"
12 size="lg"
13 />
14
15 {/* Will show "?" as default */}
16 <Avatar size="lg" />
17
18 {/* Custom fallback text */}
19 <Avatar
20 fallback="Admin"
21 size="lg"
22 />
23</View>Error Handling
AvatarDemo.jsx
1<View style={{ flexDirection: 'row', gap: 12, alignItems: 'center' }}>
2 {/* Valid image */}
3 <Avatar
4 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
5 alt="Valid Image"
6 size="lg"
7 />
8
9 {/* Broken image URL - will fallback to initials */}
10 <Avatar
11 src="https://broken-url.com/image.jpg"
12 alt="Broken Image"
13 size="lg"
14 />
15
16 {/* No image provided - shows initials */}
17 <Avatar
18 alt="No Image User"
19 size="lg"
20 />
21</View>Custom Styling
AvatarDemo.jsx
1<View style={{ flexDirection: 'row', gap: 12, alignItems: 'center' }}>
2 {/* Custom border */}
3 <Avatar
4 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
5 alt="Custom Border"
6 size="lg"
7 className="border-2 border-blue-500"
8 />
9
10 {/* Custom fallback styling */}
11 <Avatar
12 alt="Custom Fallback"
13 size="lg"
14 fallbackClassName="text-white font-bold"
15 className="bg-gradient-to-r from-purple-500 to-pink-500"
16 />
17
18 {/* Shadow effect */}
19 <Avatar
20 src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150"
21 alt="Shadow Effect"
22 size="lg"
23 className="shadow-lg"
24 />
25</View>User List
AvatarDemo.jsx
1const users = [
2 { id: 1, name: "John Doe", avatar: "https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=150" },
3 { id: 2, name: "Jane Smith", avatar: null },
4 { id: 3, name: "Bob Johnson", avatar: "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=150" },
5];
6
7<View style={{ gap: 12 }}>
8 {users.map(user => (
9 <View key={user.id} style={{ flexDirection: 'row', alignItems: 'center', gap: 12 }}>
10 <Avatar
11 src={user.avatar}
12 alt={user.name}
13 size="default"
14 />
15 <Text style={{ fontSize: 16, fontWeight: '500' }}>
16 {user.name}
17 </Text>
18 </View>
19 ))}
20</View>