Avatar

The avatar component displays user profile pictures, initials, or icons with support for various shapes, sizes, and status indicators.

BorderedClickableShow Upload Button

Preview

Interactive Avatar

Current settings:

• Size: md
• Shape: circle
• Type: image
• Status: None
• Bordered: No
• Clickable: No
• Upload: Disabled

All Sizes

Extra Small

Small

Medium

Large

Extra Large

All Shapes

Circle

Square

Rounded

Hexagon

Pentagon

Star

Diamond

All Types

Image

Letter

JD

Icon

Fallback

Status Indicators

Online

Offline

Away

Busy

Code

<Avatar 
  src="https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=400&h=400&fit=crop"
  
  
  size="md"
  shape="circle"
  
  
  
  
  
  
  alt="User avatar"
/>

Installation

CLI

ignix add component avatar

Manual

'use client';

import { motion } from 'framer-motion';
import React, { useState, useRef, forwardRef, useEffect } from 'react';
import { cva } from 'class-variance-authority';
import { cn } from '../../../utils/cn';
import { User } from 'lucide-react';

// Define all available shapes
export type AvatarShape =
| 'circle' | 'square' | 'rounded' | 'decagon'
| 'hexagon' | 'pentagon' | 'star' | 'diamond'
| 'triangle' | 'triangle-down' | 'parallelogram' | 'rhombus'
| 'cross' | 'octagon' | 'ellipse' | 'egg' |
'trapezoid';

// Shape styles using clip-path
const shapeStyles: Record<AvatarShape, React.CSSProperties> = {
// Basic shapes
circle: {},
square: {},
rounded: {},

// Polygon shapes
hexagon: {
    clipPath: 'polygon(25% 0%, 75% 0%, 100% 50%, 75% 100%, 25% 100%, 0% 50%)'
},
pentagon: {
    clipPath: 'polygon(50% 0%, 100% 38%, 82% 100%, 18% 100%, 0% 38%)'
},
octagon: {
    clipPath: 'polygon(30% 0%, 70% 0%, 100% 30%, 100% 70%, 70% 100%, 30% 100%, 0% 70%, 0% 30%)'
},
decagon: {
    clipPath: 'polygon(50% 0%, 80% 10%, 100% 35%, 100% 70%, 80% 90%, 50% 100%, 20% 90%, 0% 70%, 0% 35%, 20% 10%)'
},

// Star shapes
star: {
    clipPath: 'polygon(50% 0%, 61% 35%, 98% 35%, 68% 57%, 79% 91%, 50% 70%, 21% 91%, 32% 57%, 2% 35%, 39% 35%)'
},

// Diamond/Rhombus variations
diamond: {
    clipPath: 'polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)'
},
rhombus: {
    clipPath: 'polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)'
},

// Triangle variations
triangle: {
    clipPath: 'polygon(50% 0%, 0% 100%, 100% 100%)',
},
'triangle-down': {
    clipPath: 'polygon(0% 0%, 100% 0%, 50% 100%)'
},

// Other geometric shapes
parallelogram: {
    clipPath: 'polygon(25% 0%, 100% 0%, 75% 100%, 0% 100%)'
},
trapezoid: {
    clipPath: 'polygon(20% 0%, 80% 0%, 100% 100%, 0% 100%)'
},
ellipse: {
    clipPath: 'ellipse(50% 50% at 50% 50%)'
},
egg: {
    clipPath: 'ellipse(40% 50% at 50% 50%)'
},
// Symbol shapes
cross: {
    clipPath: 'polygon(20% 0%, 80% 0%, 80% 20%, 100% 20%, 100% 80%, 80% 80%, 80% 100%, 20% 100%, 20% 80%, 0% 80%, 0% 20%, 20% 20%)'
},
};

// Updated avatar variants with new shapes
const avatarVariants = cva(
'relative inline-flex items-center justify-center overflow-hidden font-semibold text-foreground select-none',
{
    variants: {
        size: {
            xs: 'h-6 w-6 text-xs',
            sm: 'h-8 w-8 text-sm',
            md: 'h-10 w-10 text-base',
            lg: 'h-12 w-12 text-lg',
            xl: 'h-14 w-14 text-xl',
            '2xl': 'h-16 w-16 text-2xl',
            '3xl': 'h-20 w-20 text-2xl',
            '4xl': 'h-24 w-24 text-3xl',
            '5xl': 'h-28 w-28 text-4xl',
            '6xl': 'h-32 w-32 text-5xl',
            '7xl': 'h-36 w-36 text-6xl',
            '8xl': 'h-40 w-40 text-7xl',
            '9xl': 'h-44 w-44 text-8xl',
        },
        shape: {
            // Basic shapes (use border-radius)
            circle: 'rounded-full',
            square: 'rounded-none',
            rounded: 'rounded-md',

            // Custom shapes (will use clip-path)
            hexagon: '',
            pentagon: '',
            star: '',
            diamond: '',
            triangle: '',
            'triangle-down': '',
            parallelogram: '',
            rhombus: '',
            cross: '',
            octagon: '',
            decagon: '',
            ellipse: '',
            egg: '',
            trapezoid: '',
        },
        bordered: {
            true: 'border-2 border-background',
            false: 'border-0',
        },
        clickable: {
            true: 'cursor-pointer transition-transform hover:scale-105 active:scale-95',
            false: 'cursor-default',
        },
        hasBackground: {
            true: 'bg-slate-100 dark:bg-slate-300',
            false: 'bg-transparent',
        },
    },
    defaultVariants: {
        size: 'md',
        shape: 'circle',
        bordered: false,
        clickable: false,
        hasBackground: false, // Default to having background
    },
}
);

const statusVariants = cva('absolute rounded-full border-2 border-background z-10', {
variants: {
    size: {
        xs: 'h-2 w-2 bottom-0 right-0',
        sm: 'h-2.5 w-2.5 bottom-0 right-0',
        md: 'h-3 w-3 bottom-0 right-0',
        lg: 'h-3.5 w-3.5 bottom-0 right-0',
        xl: 'h-4 w-4 bottom-0 right-0',
        '2xl': 'h-5 w-5 bottom-1 right-1',
        '3xl': 'h-6 w-6 bottom-1 right-1',
        '4xl': 'h-7 w-7 bottom-1 right-1',
        '5xl': 'h-8 w-8 bottom-2 right-2',
        '6xl': 'h-9 w-9 bottom-2 right-2',
        '7xl': 'h-10 w-10 bottom-2 right-2',
        '8xl': 'h-11 w-11 bottom-3 right-3',
        '9xl': 'h-12 w-12 bottom-3 right-3',
    },
    status: {
        online: 'bg-green-500',
        offline: 'bg-gray-400',
        away: 'bg-yellow-500',
        busy: 'bg-red-500',
    },
},
defaultVariants: {
    size: 'md',
    status: 'online',
},
});

export interface AvatarProps
extends Omit<React.HTMLAttributes<HTMLDivElement>, 'size'> {
src?: string;
alt?: string;
fallback?: React.ReactNode;
fallbackDelay?: number;
shape?: AvatarShape;
icon?: React.ReactNode;
letters?: string;
showUploadButton?: boolean;
onUpload?: (file: File) => void;
onRemove?: () => void;
status?: 'online' | 'offline' | 'away' | 'busy';
bordered?: boolean;
clickable?: boolean;
size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' | '7xl' | '8xl' | '9xl';
backgroundColor?: string; // Optional custom background color
}

const Avatar = forwardRef<HTMLDivElement, AvatarProps>(
(
    {
        className,
        size,
        shape = 'circle',
        src,
        alt = 'Avatar',
        fallback,
        // fallbackDelay = 600,
        icon,
        letters,
        status,
        bordered = false,
        clickable = false,
        backgroundColor,
        ...props
    },
    ref
) => {
    const [imageError, setImageError] = useState(false);
    const [imageLoading, setImageLoading] = useState(!!src);
    const fallbackTimerRef = useRef<NodeJS.Timeout>();

    useEffect(() => {
        if (!src) {
            setImageError(false);
            setImageLoading(false);
            return;
        }

        setImageError(false);
        setImageLoading(true);
    }, [src]);

    const handleImageError = () => {
        if (fallbackTimerRef.current) {
            clearTimeout(fallbackTimerRef.current);
        }
        setImageError(true);
        setImageLoading(false);
    };

    const handleImageLoad = () => {
        if (fallbackTimerRef.current) {
            clearTimeout(fallbackTimerRef.current);
        }
        setImageLoading(false);
    };

    const getLetters = () => {
        if (!letters) return '';
        const words = letters.trim().split(/\s+/);
        if (words.length >= 2) {
            return `${words[0][0]}${words[1][0]}`.toUpperCase();
        }
        return letters.slice(0, 2).toUpperCase();
    };

    const getShapeStyle = () => {
        // Only apply clip-path for custom shapes (not circle, square, rounded)
        if (shape && ['circle', 'square', 'rounded'].includes(shape)) {
            return undefined;
        }
        return shapeStyles[shape as AvatarShape];
    };

    const getContainerStyle = () => {
        const style: React.CSSProperties = {};

        // Apply custom background color if provided
        if (backgroundColor) {
            style.backgroundColor = backgroundColor;
        }

        // Apply clip-path to container for custom shapes
        if (shape && !['circle', 'square', 'rounded'].includes(shape)) {
            const shapeStyle = shapeStyles[shape as AvatarShape];
            if (shapeStyle.clipPath) {
                style.clipPath = shapeStyle.clipPath;
            }
        }

        return style;
    };

    const renderContent = () => {
        const customShapeStyle = getShapeStyle();

        if (src && !imageError) {
            return (
                <img
                    src={src}
                    alt={alt}
                    className="h-full w-full object-cover"
                    style={customShapeStyle}
                    onError={handleImageError}
                    onLoad={handleImageLoad}
                    loading="lazy"
                    decoding="async"
                    aria-label={alt}
                />
            );
        }

        // Show loading state if image is still loading
        if (imageLoading) {
            return (
                <div
                    className="h-full w-full flex items-center justify-center"
                    style={customShapeStyle}
                >
                    <div className="animate-pulse bg-muted-foreground/20 rounded-full h-1/2 w-1/2" />
                </div>
            );
        }

        // Fallback content when image fails or no src
        const content = fallback ? (
            <div className="h-full w-full flex items-center justify-center">{fallback}</div>
        ) : icon ? (
            <div className="h-full w-full flex items-center justify-center">{icon}</div>
        ) : letters ? (
            <span className="font-bold">{getLetters()}</span>
        ) : (
            <User className="h-1/2 w-1/2 text-gray-500 dark:text-gray-400" aria-hidden="true" />
        );

        return (
            <div
                className="h-full w-full flex items-center justify-center"
                style={customShapeStyle}
            >
                {content}
            </div>
        );
    };

    return (
        <div className="relative inline-block">
            <motion.div
                ref={ref}
                className={cn(
                    avatarVariants({
                        size,
                        shape,
                        bordered,
                        clickable,
                        hasBackground: !backgroundColor // Only use default background if no custom color
                    }),
                    className,
                    'group'
                )}
                style={getContainerStyle()}
                whileHover={clickable ? { scale: 1.05 } : undefined}
                whileTap={clickable ? { scale: 0.95 } : undefined}
                {...props}
            >
                {renderContent()}
            </motion.div>

            {/* Status indicator positioned outside */}
            {status && (
                <div
                    className={cn(statusVariants({ size, status }))}
                    aria-label={`Status: ${status}`}
                    role="status"
                />
            )}
        </div>
    );
}
);

Avatar.displayName = 'Avatar';

export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
children: React.ReactNode;
max?: number;
spacing?: number;
size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' | '7xl' | '8xl' | '9xl';
}

const AvatarGroup = forwardRef<HTMLDivElement, AvatarGroupProps>(
({ children, max, spacing = -4, size = 'md', className, ...props }, ref) => {
    const childrenArray = React.Children.toArray(children);
    const totalChildren = childrenArray.length;
    const displayChildren = max ? childrenArray.slice(0, max) : childrenArray;
    const extraCount = max && totalChildren > max ? totalChildren - max : 0;

    return (
        <div
            ref={ref}
            className={cn('flex items-center', className)}
            style={{ marginLeft: `${Math.abs(spacing)}px` }}
            role="group"
            aria-label="Avatar group"
            {...props}
        >
            {displayChildren.map((child, index) => (
                <div
                    key={index}
                    className="relative"
                    style={{ marginLeft: `${spacing}px` }}
                >
                    {React.isValidElement<AvatarProps>(child)
                        ? React.cloneElement(child, {
                            bordered: true,
                            size: child.props.size || size,
                        })
                        : child}
                </div>
            ))}
            {extraCount > 0 && (
                <div className="relative" style={{ marginLeft: `${spacing}px` }}>
                    {/* Create a motion.div that matches the Avatar structure exactly */}
                    <motion.div
                        className={cn(
                            avatarVariants({
                                size,
                                shape: 'circle',
                                bordered: true,
                                clickable: false,
                                hasBackground: true,
                            }),
                            'bg-gray-200 dark:bg-gray-700 flex items-center justify-center'
                        )}
                        aria-label={`${extraCount} more avatars`}
                        role="status"
                    >
                        <span className="font-bold">+{extraCount}</span>
                    </motion.div>
                </div>
            )}
        </div>
    );
}
);


AvatarGroup.displayName = 'AvatarGroup';

export { Avatar, AvatarGroup };

Usage

Import the component:

import { Avatar, AvatarGroup } from '@ignix-ui/avatar';

Basic Usage

The Avatar component can be used to display user profile images with fallbacks.

Preview

Code

import { Avatar } from '@ignix-ui/avatar';

function BasicAvatar() {
  return (
    <Avatar 
      src="https://example.com/avatar.jpg" 
      alt="User avatar" 
      size='2xl'
    />
  );
}

Examples

Avatar with Status Indicator

Preview

Online

Away

Busy

Offline

Code

function AvatarWithStatus() {
    return (
        <div className="flex flex-wrap gap-6 items-center justify-center">
                <div className="flex flex-col items-center gap-2">
                    <Avatar 
                        src="https://example.com/avatar.jpg"
                        status="online" 
                        alt="Online user" 
                        size='2xl'
                    />
                    <p>Online</p>
                </div>
                <div className="flex flex-col items-center gap-2">
                    <Avatar 
                        src="https://example.com/avatar.jpg"
                        status="away" 
                        alt="Away user" 
                        size='2xl'
                    />
                    <p>Away</p>
                </div>
                <div className="flex flex-col items-center gap-2">
                    <Avatar 
                        src="https://example.com/avatar.jpg"
                        status="busy" 
                        alt="Busy user" 
                        size='2xl'
                />
                <p>Busy</p>
                </div>
                <div className="flex flex-col items-center gap-2">
                    <Avatar 
                        src="https://example.com/avatar.jpg"
                        status="offline" 
                        alt="Offline user" 
                    size='2xl'
                />
                <p>Offline</p>
                </div>
            </div>
    );
}

Different Shapes

Preview

Square

Circle

Rounded

Hexagon

Pentagon

Octagon

Rhombus

Code

function AvatarShapes() {
    return (
        <div className="p-4 border rounded-lg">
                <div className="flex flex-wrap gap-6 items-center justify-center">
                <div className="flex flex-col items-center gap-2">
                        <Avatar 
                            src="https://example.com/avatar.jpg"
                            shape="square" 
                            alt="Square" 
                            size='2xl'
                        />
                        <p>Square</p>
                    </div>
                    <div className="flex flex-col items-center gap-2">
                        <Avatar 
                            src="https://example.com/avatar.jpg"
                            shape="circle" 
                            alt="Circle" 
                            size='2xl'
                        />
                        <p>Circle</p>
                    </div>
                    <div className="flex flex-col items-center gap-2">
                        <Avatar 
                            src="https://example.com/avatar.jpg"
                            shape="rounded" 
                            alt="Rounded" 
                            size='2xl'
                        />
                        <p>Rounded</p>
                    </div>
                    <div className="flex flex-col items-center gap-2">
                        <Avatar 
                            src="https://example.com/avatar.jpg"
                            shape="hexagon"
                            alt="Hexagon" 
                            size='2xl'
                        />
                        <p>Hexagon</p>
                    </div>
                    <div className="flex flex-col items-center gap-2">
                        <Avatar 
                            src="https://example.com/avatar.jpg"
                            shape="pentagon"
                            alt='Pentagon'
                            size='2xl'
                        />
                        <p>Pentagon</p>
                    </div>
                    <div className="flex flex-col items-center gap-2">
                        <Avatar 
                            src="https://example.com/avatar.jpg"
                            shape="octagon"
                            alt='Octagon'
                            size='2xl'
                        />
                        <p>Octagon</p>
                    </div>
                    <div className="flex flex-col items-center gap-2">
                        <Avatar 
                            src="https://example.com/avatar.jpg"
                            shape="rhombus"
                            alt='Rhombus'
                            size='2xl'
                        />
                        <p>Rhombus</p>
                    </div>
                </div>
            </div>
        </div>
    );
}

Different Sizes

Preview

Code

function AvatarSizes() {
    return (
        <div className="flex flex-wrap gap-6 items-center">
            <Avatar shape='circle' src="https://example.com/avatar.jpg" alt="Extra Small" size='xs' />
            <Avatar shape='circle' src="https://example.com/avatar.jpg" alt="Small" size='sm' />
            <Avatar shape='circle' src="https://example.com/avatar.jpg" alt="Medium" size='md' />
            <Avatar shape='circle' src="https://example.com/avatar.jpg" alt="Large" size='lg' />
            <Avatar shape='circle' src="https://example.com/avatar.jpg" alt="Extra Large" size='xl' />
            <Avatar shape='circle' src="https://example.com/avatar.jpg" alt="2XL" size='2xl' />
            <Avatar shape='circle' src="https://example.com/avatar.jpg" alt="3XL" size='3xl' />
            <Avatar shape='circle' src="https://example.com/avatar.jpg" alt="4XL" size='4xl' />
            <Avatar shape='circle' src="https://example.com/avatar.jpg" alt="5XL" size='5xl' />
        </div>
    );
}

Avatar with Initial Letters

Preview

JD

AS

BJ

ED

Code

function InitialsAvatar() {
    return (
        <div className="flex flex-wrap gap-6 items-center justify-center">
            <Avatar backgroundColor='#ef4444' shape="circle" letters="John Doe" alt="Initials avatar" size="2xl" />
            <Avatar backgroundColor='#ef4444' shape="square" letters="Alice Smith" alt="Initials avatar" size="2xl" />
            <Avatar backgroundColor='#ef4444' shape="circle" letters="Baby Johnson" alt="Initials avatar" size="2xl" />
            <Avatar backgroundColor='#ef4444' shape="square" letters="Emily Davis" alt="Initials avatar" size="2xl" />
        </div>
    );
}

Avatar with Icon

Preview

Code

import { Avatar } from '@ignix-ui/avatar';

import { User, Mail, Star, Camera, Settings, Users, Bell } from 'lucide-react';

function IconAvatar() {
    return (
        <div className="flex flex-wrap gap-6 items-center justify-center">
            <Avatar 
                icon={<User className="h-1/2 w-1/2 text-white" aria-hidden="true" />} 
                alt='Icon avatar' 
                size='2xl' 
                backgroundColor='#ef4444' 
            />
            <Avatar 
                icon={<Mail className="h-1/2 w-1/2 text-white" aria-hidden="true" />} 
                alt="Icon avatar" 
                size='2xl' 
                backgroundColor='#ef4444' 
            />
            <Avatar 
                icon={<Star className="h-1/2 w-1/2 text-white" aria-hidden="true" />} 
                alt="Icon avatar" 
                size='2xl' 
                backgroundColor='#ef4444' 
            />
            <Avatar 
                icon={<Settings className="h-1/2 w-1/2 text-white" aria-hidden="true" />} 
                alt="Icon avatar" 
                size='2xl' 
                backgroundColor='#ef4444' 
            />
            <Avatar 
                icon={<Bell className="h-1/2 w-1/2 text-white" aria-hidden="true" />} 
                alt="Icon avatar" 
                size='2xl' 
                backgroundColor='#ef4444' 
            />
        </div>
    );
}

Avatar Group

Preview

+4

+2

+5

Code

function GroupedAvatars() {
    return (
        <AvatarGroup size='lg' max={4} spacing={-15}>
            <Avatar src="https://example.com/avatar1.jpg" alt="User 1" />
            <Avatar src="https://example.com/avatar2.jpg" alt="User 2" />
            <Avatar src="https://example.com/avatar3.jpg" alt="User 3" />
            <Avatar src="https://example.com/avatar4.jpg" alt="User 4" />
            <Avatar src="https://example.com/avatar5.jpg" alt="User 5" />
            <Avatar src="https://example.com/avatar6.jpg" alt="User 6" />
            <Avatar src="https://example.com/avatar7.jpg" alt="User 7" />
            <Avatar src="https://example.com/avatar8.jpg" alt="User 8" />
        </AvatarGroup>
        <AvatarGroup size='2xl' max={6} spacing={-10}>
            <Avatar src="https://example.com/avatar1.jpg" alt="User 1" />
            <Avatar src="https://example.com/avatar2.jpg" alt="User 2" />
            <Avatar src="https://example.com/avatar3.jpg" alt="User 3" />
            <Avatar src="https://example.com/avatar4.jpg" alt="User 4" />
            <Avatar src="https://example.com/avatar5.jpg" alt="User 5" />
            <Avatar src="https://example.com/avatar6.jpg" alt="User 6" />
            <Avatar src="https://example.com/avatar7.jpg" alt="User 7" />
            <Avatar src="https://example.com/avatar8.jpg" alt="User 8" />
        </AvatarGroup>
        <AvatarGroup size='3xl' max={3} spacing={-30}>
            <Avatar src="https://example.com/avatar1.jpg" alt="User 1" />
            <Avatar src="https://example.com/avatar2.jpg" alt="User 2" />
            <Avatar src="https://example.com/avatar3.jpg" alt="User 3" />
            <Avatar src="https://example.com/avatar4.jpg" alt="User 4" />
            <Avatar src="https://example.com/avatar5.jpg" alt="User 5" />
            <Avatar src="https://example.com/avatar6.jpg" alt="User 6" />
            <Avatar src="https://example.com/avatar7.jpg" alt="User 7" />
            <Avatar src="https://example.com/avatar8.jpg" alt="User 8" />
        </AvatarGroup>
    );
}

Props

Avatar

Prop	Type	Default	Description
src	string	-	Image source URL
alt	string	'Avatar'	Alternative text for screen readers
fallback	React.ReactNode	-	Custom fallback content when image fails to load
fallbackDelay	number	600	Delay in ms before showing fallback
shape	'circle' | 'square' | 'rounded' | 'decagon' | 'hexagon' | 'pentagon' | 'star' | 'diamond' | 'triangle' | 'triangle-down' | 'parallelogram' | 'rhombus' | 'cross' | 'octagon' | 'ellipse' | 'egg' | 'trapezoid'	'circle'	Shape of the avatar
icon	React.ReactNode	-	Icon component to display
letters	string	-	Text to display as initials (e.g., "John Doe")
status	'online' | 'offline' | 'away' | 'busy'	-	Status indicator
bordered	boolean	false	Add border around avatar
clickable	boolean	false	Make avatar clickable with hover effects
size	'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' | '7xl' | '8xl' | '9xl'	'md'	Size of the avatar
backgroundColor	string	-	Optional custom background color
onClick	React.MouseEventHandler<HTMLDivElement>	-	Click handler for the avatar
className	string	-	Additional CSS classes
ref	React.Ref<HTMLDivElement>	-	Ref to the avatar element

AvatarGroup

Prop	Type	Default	Description
children	React.ReactNode	-	Avatar components to group
max	number	-	Maximum number of avatars to show before displaying "+X"
spacing	number	-4	Spacing between avatars (negative for overlap)
size	'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | '6xl' | '7xl' | '8xl' | '9xl'	'md'	Size for all avatars in the group (can be overridden by individual avatars)
className	string	-	Additional CSS classes
ref	React.Ref<HTMLDivElement>	-	Ref to the avatar group element