astro-gravatar

Astro components for integrating Gravatar avatars and profiles into your Astro site.

✨ Features

• 🎨 Beautiful Components - Ready-to-use avatar and profile card components
• 🚀 Performance Optimized - Built-in caching, lazy loading, and image optimization
• 🔒 TypeScript Support - Full type safety with comprehensive interfaces
• 🎭 Customizable - Extensive styling and layout options
• 📱 Responsive - Mobile-friendly with accessibility features
• 🌐 SSR Compatible - Works seamlessly with Astro's server-side rendering

🚀 Quick Start

Installation

bun add astro-gravatar

Basic Usage

---
import GravatarAvatar from 'astro-gravatar';
---

<GravatarAvatar email="[email protected]" size={120} />

Profile Cards

---
import GravatarProfileCard from 'astro-gravatar/GravatarProfileCard';
---

<GravatarProfileCard
  email="[email protected]"
  layout="card"
  showVerified
  showLinks
/>

QR Codes

---
import GravatarQR from 'astro-gravatar/GravatarQR';
---

<GravatarQR
  email="[email protected]"
  size={150}
  version={3}
  type="gravatar"
  utmMedium="web"
  utmCampaign="profile_share"
/>

📖 Documentation

• Quick Start Guide - Get up and running in minutes
• Component Reference - Complete API documentation

🎯 Components

GravatarAvatar

Display a Gravatar avatar with extensive customization:

<GravatarAvatar
  email="[email protected]"
  size={150}
  rating="pg"
  default="identicon"
  class="rounded-full"
  lazy={true}
/>

GravatarProfileCard

Display a complete profile card with avatar and user information:

<GravatarProfileCard
  email="[email protected]"
  layout="horizontal"
  avatarSize={100}
  showName
  showBio
  showVerified
/>

GravatarQR

Display a QR code that links to a user's Gravatar profile:

<GravatarQR
  email="[email protected]"
  size={150}
  version={3}
  type="gravatar"
  utmMedium="web"
  utmCampaign="profile_share"
  class="qr-code"
/>

🛠️ Utilities

Access the underlying utilities for custom implementations:

---
import { buildAvatarUrl, buildQRCodeUrl, getProfile } from 'astro-gravatar';

// Build custom avatar URL
const avatarUrl = buildAvatarUrl('[email protected]', { size: 200 });

// Build QR code URL
const qrUrl = buildQRCodeUrl('[email protected]', { size: 150, version: 3 });

// Fetch profile data
const profile = await getProfile('[email protected]');
---

<img src={avatarUrl} alt="User Avatar" />
<img src={qrUrl} alt="QR Code" />
<h1>{profile.display_name}</h1>

🎨 Styling

Components include sensible defaults but are fully customizable:

/* Custom avatar styling */
.my-avatar {
  border-radius: 50%;
  border: 3px solid #3b82f6;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  transition: transform 0.2s ease;
}

.my-avatar:hover {
  transform: scale(1.05);
}

🔧 Configuration

All components support extensive configuration options:

Avatar Options

• size - Avatar size in pixels (1-2048)
• rating - Content rating level (g, pg, r, x)
• default - Default image for missing avatars
• lazy - Enable lazy loading

Profile Card Options

• layout - Layout style (horizontal, vertical, card)
• template - Content template (default, compact, detailed)
• showName, showBio, showVerified, showLinks - Toggle content sections

QR Code Options

• size - QR code size in pixels (1-1000, default: 80)
• version - QR code style version (1: standard, 3: modern dots)
• type - Center icon type (user, gravatar, none)
• utmMedium - UTM medium parameter for tracking
• utmCampaign - UTM campaign parameter for tracking

📝 TypeScript Support

Full TypeScript support with comprehensive types:

import type { GravatarProfile, GravatarAvatarProps } from 'astro-gravatar';

// Use types in your components
const profile: GravatarProfile = await getProfile('[email protected]');

🚀 Performance Features

• Built-in Caching - Reduces API calls and improves performance
• Lazy Loading - Images load only when needed
• Responsive Images - Automatic srcset generation
• Optimized URLs - Efficient Gravatar URL construction

🌍 Browser Support

• Modern browsers with ES6 module support
• Progressive enhancement for JavaScript-disabled environments
• Responsive design with accessibility features

🧞 Commands

All commands are run from the root of the project, from a terminal:

| Command | Action | | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bun link | Registers this package locally. Run bun link astro-gravatar in an Astro project to install your components | | bun publish | Publishes this package to NPM. Requires you to be logged in | | bun run typecheck | Check TypeScript types without building |

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines for details.

🙏 Acknowledgments

• Gravatar for the avatar service
• Astro for the amazing framework
• The community for feedback and support