A versatile Avatar component for displaying user profile images, initials, or icons with a hand-drawn aesthetic and status indicators.

Avatar

The Avatar component in Faiz UI provides a hand-drawn sketch aesthetic for displaying user profile images, initials, or icons. It includes comprehensive status indicator functionality, multiple size options, and various customization features while maintaining the unique visual flair of the design system.

Installation

npm install @faiz-ui/avatar
# or
pnpm add @faiz-ui/avatar

Usage

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function AvatarUsage() {
  return (
    <div className="flex flex-wrap gap-4">
      <Avatar name="John Doe" />
      <Avatar name="Jane Smith" color="secondary" />
      <Avatar initials="AB" color="success" />
    </div>
  );
}

Sizes

Avatars are available in different sizes to fit various UI contexts, from compact lists to prominent profile displays.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function Sizes() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Avatar name="XS" size="xs" />
      <Avatar name="SM" size="sm" />
      <Avatar name="MD" size="md" />
      <Avatar name="LG" size="lg" />
      <Avatar name="XL" size="xl" />
    </div>
  );
}

Colors

Avatars come in various color options to match your design system and convey different meanings.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function Colors() {
  return (
    <div className="flex flex-wrap gap-4">
      <Avatar name="Primary" color="primary" />
      <Avatar name="Secondary" color="secondary" />
      <Avatar name="Success" color="success" />
      <Avatar name="Warning" color="warning" />
      <Avatar name="Danger" color="danger" />
      <Avatar name="Info" color="info" />
    </div>
  );
}

With Images

Avatars can display profile images with automatic fallback to initials when the image fails to load.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function WithImages() {
  return (
    <div className="flex flex-wrap gap-4">
      <Avatar 
        name="John Doe" 
        src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80"
        alt="John Doe"
      />
      <Avatar 
        name="Jane Smith" 
        src="https://images.unsplash.com/photo-1494790108755-2616b9e0e4b0?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80"
        alt="Jane Smith"
        color="secondary"
      />
      <Avatar 
        name="Fallback Example" 
        src="invalid-url.jpg"
        color="success"
      />
    </div>
  );
}

Status Indicators

Display user status with colored dots that are properly positioned and fully visible across all avatar variants.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function StatusIndicators() {
  return (
    <div className="flex flex-wrap gap-4">
      <Avatar name="Online" showStatus status="online" />
      <Avatar name="Away" showStatus status="away" />
      <Avatar name="Busy" showStatus status="busy" />
      <Avatar name="Offline" showStatus status="offline" />
    </div>
  );
}

Status with Different Sizes

Status indicators automatically scale and position correctly for all avatar sizes.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function StatusWithSizes() {
  return (
    <div className="flex flex-wrap items-center gap-4">
      <Avatar name="XS" size="xs" showStatus status="online" />
      <Avatar name="SM" size="sm" showStatus status="away" />
      <Avatar name="MD" size="md" showStatus status="busy" />
      <Avatar name="LG" size="lg" showStatus status="offline" />
      <Avatar name="XL" size="xl" showStatus status="online" />
    </div>
  );
}

Status with Images

Status indicators work seamlessly with profile images, maintaining visibility and proper positioning.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function StatusWithImages() {
  return (
    <div className="flex flex-wrap gap-4">
      <Avatar 
        name="Online User" 
        src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80"
        showStatus 
        status="online" 
      />
      <Avatar 
        name="Away User" 
        src="https://images.unsplash.com/photo-1494790108755-2616b9e0e4b0?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80"
        showStatus 
        status="away" 
      />
      <Avatar 
        name="Busy User" 
        src="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80"
        showStatus 
        status="busy" 
      />
    </div>
  );
}

Status with Different Variants

Status indicators maintain visibility across all avatar variants including different colors and border styles.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function StatusWithVariants() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-wrap gap-4">
        <Avatar name="Primary" color="primary" showStatus status="online" />
        <Avatar name="Secondary" color="secondary" showStatus status="away" />
        <Avatar name="Success" color="success" showStatus status="online" />
        <Avatar name="Warning" color="warning" showStatus status="busy" />
        <Avatar name="Danger" color="danger" showStatus status="offline" />
        <Avatar name="Info" color="info" showStatus status="online" />
      </div>
      
      <div className="flex flex-wrap gap-4">
        <Avatar name="No Border" isBordered={false} showStatus status="online" />
        <Avatar name="No Border" isBordered={false} showStatus status="away" color="secondary" />
        <Avatar name="No Border" isBordered={false} showStatus status="busy" color="warning" />
        <Avatar name="No Border" isBordered={false} showStatus status="offline" color="danger" />
      </div>
    </div>
  );
}

Custom Icons

Replace the default user icon or initials with custom icons for specialized use cases.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function CustomIcons() {
  return (
    <div className="flex flex-wrap gap-4">
      <Avatar 
        icon={
          <svg className="w-1/2 h-1/2" fill="currentColor" viewBox="0 0 24 24">
            <path d="M12 2C13.1 2 14 2.9 14 4C14 5.1 13.1 6 12 6C10.9 6 10 5.1 10 4C10 2.9 10.9 2 12 2ZM21 9V7L15 1H5C3.89 1 3 1.89 3 3V21C3 22.11 3.89 23 5 23H19C20.11 23 21 22.11 21 21V9M19 9H14V4H5V21H19V9Z" />
          </svg>
        }
        color="info"
      />
      <Avatar 
        icon={<span className="text-lg">🎨</span>}
        color="secondary"
      />
      <Avatar 
        icon={<span className="text-lg">⚙️</span>}
        color="warning"
        showStatus
        status="online"
      />
    </div>
  );
}

🎨

⚙️

Clickable Avatars

Make avatars interactive with click handling and proper accessibility support.

"use client";
 
import { Avatar } from "@faiz-ui/react";
import { useState } from "react";
 
export default function ClickableAvatars() {
  const [clickCount, setClickCount] = useState(0);
 
  return (
    <div className="flex flex-col gap-4">
      <div className="flex flex-wrap gap-4">
        <Avatar 
          name="Click Me" 
          isClickable 
          onClick={() => setClickCount(prev => prev + 1)}
        />
        <Avatar 
          name="Profile" 
          isClickable 
          onClick={() => alert('Profile clicked!')}
          showStatus
          status="online"
        />
        <Avatar 
          name="Disabled" 
          isClickable 
          isDisabled
          onClick={() => alert('This should not fire')}
        />
      </div>
      
      {clickCount > 0 && (
        <p className="text-sm text-gray-600 dark:text-gray-400">
          First avatar clicked {clickCount} times
        </p>
      )}
    </div>
  );
}

Fallback Handling

Demonstrate how avatars handle various fallback scenarios gracefully.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function FallbackHandling() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-wrap gap-4">
        <Avatar name="John Doe" />
        <Avatar initials="AB" />
        <Avatar />
        <Avatar
          fallback={<span className="text-lg">👤</span>}
        />
      </div>
 
      <div className="flex flex-wrap gap-4">
        <Avatar
          name="Broken Image"
          src="invalid-url.jpg"
          onError={() => console.log('Image failed to load')}
        />
        <Avatar
          name="Custom Fallback"
          src="another-invalid-url.jpg"
          fallback={<span className="text-lg">🖼️</span>}
        />
      </div>
    </div>
  );
}

👤

Custom Styles

Apply custom styles using Tailwind CSS classes to create unique avatar appearances.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function CustomStyles() {
  return (
    <div className="flex flex-wrap gap-4">
      <Avatar
        name="Gradient"
        customStyles="bg-gradient-to-r from-purple-400/60 to-pink-400/60"
      />
      <Avatar
        name="Dashed"
        customStyles="border-[3px] border-dashed"
      />
      <Avatar
        name="Rotated"
        customStyles="[transform:rotate(-5deg)]"
        showStatus
        status="online"
      />
      <Avatar
        name="Shadow"
        customStyles="shadow-[4px_4px_0px_0px_rgba(0,0,0,0.5)]"
      />
    </div>
  );
}

Dark Mode Support

Avatars automatically adapt to dark mode environments with appropriate styling adjustments.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function DarkMode() {
  return (
    <div className="dark bg-gray-900 p-6 rounded-lg">
      <div className="flex flex-wrap gap-4 mb-4">
        <Avatar name="Default" />
        <Avatar name="Primary" color="primary" />
        <Avatar name="Secondary" color="secondary" />
        <Avatar name="Success" color="success" />
      </div>
 
      <div className="flex flex-wrap gap-4 mb-4">
        <Avatar name="Online" showStatus status="online" />
        <Avatar name="Away" showStatus status="away" color="warning" />
        <Avatar name="Busy" showStatus status="busy" color="danger" />
        <Avatar name="Offline" showStatus status="offline" />
      </div>
 
      <div className="flex flex-wrap gap-4">
        <Avatar
          name="Image"
          src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80"
          showStatus
          status="online"
        />
        <Avatar name="No Border" isBordered={false} showStatus status="away" />
        <Avatar name="Disabled" isDisabled />
      </div>
    </div>
  );
}

Avatar Group

Create avatar groups for displaying multiple users in a compact layout.

"use client";
 
import { Avatar } from "@faiz-ui/react";
 
export default function AvatarGroup() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex -space-x-2">
        <Avatar name="John Doe" size="md" />
        <Avatar name="Jane Smith" size="md" color="secondary" />
        <Avatar name="Bob Johnson" size="md" color="success" />
        <Avatar name="Alice Brown" size="md" color="warning" />
        <Avatar initials="+5" size="md" color="info" />
      </div>
 
      <div className="flex -space-x-1.5">
        <Avatar name="Small Group" size="sm" showStatus status="online" />
        <Avatar name="User 2" size="sm" showStatus status="away" color="secondary" />
        <Avatar name="User 3" size="sm" showStatus status="busy" color="danger" />
      </div>
 
      <div className="flex -space-x-3">
        <Avatar
          name="Large User"
          size="lg"
          src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80"
        />
        <Avatar
          name="Another User"
          size="lg"
          src="https://images.unsplash.com/photo-1494790108755-2616b9e0e4b0?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80"
          color="secondary"
        />
        <Avatar name="Third User" size="lg" color="success" />
      </div>
    </div>
  );
}

Implementation Notes

The Avatar component includes automatic initials generation from user names.
Status indicators are positioned outside the content area to prevent clipping.
All status dots include proper contrast borders and shadows for visibility.
Images automatically fallback to initials when loading fails.
The hand-drawn aesthetic is consistently applied across all variants and states.
All avatars are fully accessible with keyboard navigation and screen reader support.
Status indicators scale appropriately for each avatar size.

Props

Prop	Type	Default	Description
`name`	`string`	`undefined`	The name of the user. Used to generate initials when image is not available
`src`	`string`	`undefined`	The source URL of the avatar image
`alt`	`string`	`undefined`	The alt text for the avatar image
`initials`	`string`	`undefined`	Custom initials to display instead of generated ones
`color`	`'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info'`	`'primary'`	The color theme of the avatar
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	The size of the avatar
`radius`	`'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'`	`'full'`	The border radius of the avatar
`showStatus`	`boolean`	`false`	Whether to show a status indicator
`status`	`'online' \| 'offline' \| 'away' \| 'busy'`	`'online'`	The status of the user
`icon`	`React.ReactNode`	`undefined`	Custom icon to display instead of image or initials
`fallback`	`React.ReactNode`	`undefined`	Fallback component to render when image fails to load
`isBordered`	`boolean`	`true`	Whether to show the border
`isDisabled`	`boolean`	`false`	Whether the avatar is disabled
`isClickable`	`boolean`	`false`	Whether the avatar is clickable
`onError`	`() => void`	`undefined`	Callback fired when the image fails to load
`onClick`	`(event: MouseEvent) => void`	`undefined`	Callback fired when the avatar is clicked
`customStyles`	`string`	`undefined`	Custom CSS classes to apply

Avatar

On this page