@metadiv-studio/avatar

@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