@metadiv-studio/avatar

A modern, accessible avatar component library built with React, TypeScript, and Tailwind CSS. This package provides customizable avatar components with fallback support, multiple sizes, and seamless integration with your existing design system.

🚀 Quick Start

Installation

npm i @metadiv-studio/avatar

Basic Usage

import { Avatar } from '@metadiv-studio/avatar';

function UserProfile() {
  return (
    <div>
      <Avatar text="John Doe" />
      <Avatar src="/path/to/image.jpg" alt="User avatar" />
    </div>
  );
}

📦 What's Included

This package provides:

• Avatar Component: A fully-featured avatar component with image support and fallback text
• Multiple Sizes: Pre-configured sizes (sm, md, lg, xl) for different use cases
• Fallback Support: Automatic fallback to initials when images fail to load
• Accessibility: Built on Radix UI primitives for excellent accessibility
• Tailwind CSS: Fully styled with Tailwind CSS classes
• TypeScript: Complete TypeScript support with proper type definitions
• Dark Mode: Built-in dark mode support

🎯 Features

• Responsive Design: Automatically adapts to different screen sizes
• Customizable: Easy to customize with Tailwind CSS classes
• Accessible: Follows ARIA guidelines and keyboard navigation
• Performance: Optimized rendering with React best practices
• Theme Support: Seamless integration with light/dark themes

📖 Usage Examples

Basic Avatar with Text Fallback

import { Avatar } from '@metadiv-studio/avatar';

<Avatar text="John Doe" />

Avatar with Image

<Avatar 
  src="/path/to/avatar.jpg" 
  text="John Doe" 
  alt="John Doe's profile picture" 
/>

Different Sizes

<div className="flex items-center gap-4">
  <Avatar text="A" size="sm" />
  <Avatar text="B" size="md" />
  <Avatar text="C" size="lg" />
  <Avatar text="D" size="xl" />
</div>

Custom Styling

<Avatar 
  text="E" 
  className="bg-blue-500 text-white border-2 border-blue-600" 
/>

User List Example

const users = [
  { name: "John Doe", avatar: "/john.jpg" },
  { name: "Jane Smith", avatar: "/jane.jpg" },
  { name: "Mike Johnson" }, // No avatar, will show initials
];

function UserList() {
  return (
    <div className="flex gap-2">
      {users.map((user, index) => (
        <Avatar
          key={index}
          text={user.name}
          src={user.avatar}
          alt={`${user.name}'s avatar`}
        />
      ))}
    </div>
  );
}

🎨 Props

Avatar Component Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | text | string | - | Text to display as fallback (usually user's name) | | src | string | - | URL of the avatar image | | size | "sm" \| "md" \| "lg" \| "xl" | "md" | Size of the avatar | | className | string | - | Additional CSS classes for customization |

Size Mappings

| Size | Dimensions | Use Case | |------|------------|----------| | sm | 40x40px | Compact spaces, lists | | md | 48x48px | Default size, most use cases | | lg | 64x64px | Profile headers, larger displays | | xl | 80x80px | Hero sections, prominent displays |

🎨 Styling

Default Styling

The avatar component comes with sensible defaults that work well in most contexts:

• Rounded circular design
• Subtle border with dark mode support
• Proper contrast for accessibility
• Responsive sizing

Customization

You can easily customize the appearance using Tailwind CSS classes:

<Avatar 
  text="Custom"
  className="
    bg-gradient-to-r from-blue-500 to-purple-600
    text-white
    border-4 border-white
    shadow-lg
    hover:scale-105 transition-transform
  "
/>

Dark Mode Support

The component automatically adapts to dark mode when using Tailwind's dark mode classes:

<Avatar 
  text="Dark Mode"
  className="bg-gray-800 text-white dark:bg-gray-200 dark:text-gray-800"
/>

🔧 Integration

With Tailwind CSS

To use the component's built-in Tailwind styles, ensure your tailwind.config.js includes this package:

// tailwind.config.js
module.exports = {
  content: [
    // ... other content paths
    "./node_modules/@metadiv-studio/**/*.{js,ts,jsx,tsx}",
  ],
  // ... rest of config
}

With Other Styling Solutions

The component is built with Tailwind CSS but can be customized with any CSS-in-JS solution or custom CSS classes.

🚀 Development

Local Development

# Clone the repository
git clone <repository-url>
cd avatar

# Install dependencies
npm install

# Start development server
npm run dev

Building

# Build for production
npm run build

# Clean build artifacts
npm run clean

📦 Package Information

• Package Name: @metadiv-studio/avatar
• Version: 0.1.0
• License: UNLICENSED
• Type: ES Module
• Peer Dependencies: React ^18, React-DOM ^18

🤝 Contributing

We welcome contributions! Please feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📄 License

This package is currently unlicensed. Please contact the maintainers for licensing information.

Built with ❤️ by the Metadiv Studio team