Avatar

The Avatar component is used to represent a user or entity with an image, initials, or fallback icon. It supports various sizes, shapes, and status indicators.

Import

import { Avatar } from 'rebel-ui';

Usage

Basic Avatar

<Avatar src="https://github.com/danielkosgei.png" alt="User Avatar" name="Daniel Kosgei" />

Avatar with Name Fallback

If the image fails to load or no image is provided, the avatar will display initials from the name.

<Avatar name="Daniel Kosgei" />

Avatar with Status

Show the user’s status with a small indicator.

<Avatar 
  src="https://github.com/danielkosgei.png" 
  name="Daniel Kosgei" 
  status="online" 
/>

Avatar Sizes

Available sizes: xs, sm, md, lg, xl

<Avatar size="xs" name="Daniel" />
<Avatar size="sm" name="Daniel" />
<Avatar size="md" name="Daniel" />
<Avatar size="lg" name="Daniel" />
<Avatar size="xl" name="Daniel" />

Avatar Shapes

Choose between circle (default) and square shapes.

<Avatar shape="circle" name="Daniel" />
<Avatar shape="square" name="Daniel" />

Bordered Avatar

Add a border around the avatar.

<Avatar src="https://github.com/danielkosgei.png" bordered name="Daniel" />

Custom Fallback Icon

Provide a custom fallback icon when no image or name is available.

<Avatar 
  fallbackIcon={() => `
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-circle-user-icon lucide-circle-user"><circle cx="12" cy="12" r="10"/><circle cx="12" cy="10" r="3"/>
        <path d="M7 20.662V19a2 2 0 0 1 2-2h6a2 2 0 0 1 2 2v1.662"/>
    </svg>
  `} 
/>

Props

Prop	Type	Default	Description
src	string	''	URL of the avatar image
alt	string	''	Alternative text for the avatar image
name	string	''	Name to display as initials when image is not available
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'	'md'	Size of the avatar
shape	'circle' \| 'square'	'circle'	Shape of the avatar
status	'online' \| 'offline' \| 'away' \| 'busy'	undefined	Status indicator
bordered	boolean	false	Whether to show a border around the avatar
fallbackIcon	() => string	undefined	Custom SVG icon to show when no image or name is available

Sizes

Size	Dimensions	Font Size
xs	1.5rem	0.75rem
sm	2rem	0.875rem
md	2.5rem	1rem
lg	3rem	1.125rem
xl	4rem	1.5rem

Accessibility

• The avatar uses appropriate ARIA labels based on the provided alt text or name
• Status indicators include ARIA labels describing the current status
• The component uses semantic HTML and proper role attributes
• When used as a decorative element, the avatar is marked with role="presentation"

Examples

Group of Avatars

<div class="flex flex-col gap-4">
    <Avatar shape="square" bordered src="/user1.jpg" name="User A" />
    <Avatar shape="square" bordered src="/user2.jpg" name="User B" />
    <Avatar shape="square" bordered src="/user3.jpg" name="User C" />
</div>

Avatar with Different Status States

<div class="flex flex-col gap-4">
    <Avatar shape="square" bordered src="/user1.jpg" name="User A" status="online" />
    <Avatar shape="square" bordered src="/user2.jpg" name="User B" status="away" />
    <Avatar shape="square" bordered src="/user3.jpg" name="User C" status="busy" />
    <Avatar shape="square" bordered src="/user3.jpg" name="User D" status="offline" />
</div>

Fallback Behavior

The Avatar component has a fallback chain:

1. Displays the image if src is provided and loads successfully
2. Shows initials if name is provided and image fails or is not provided
3. Uses custom fallback icon if provided through fallbackIcon prop
4. Falls back to default user icon if none of the above are available