Basic Usage Examples

This guide demonstrates how to use astro-gravatar components in common scenarios.

Simple Avatar Display

Display individual user avatars with different styles and sizes.

Small (50px)

Medium (80px)

Large (120px)

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

<GravatarAvatar email="user@example.com" size={80} class="rounded-full" />

Different Avatar Styles

Explore different default avatar styles for users without Gravatars.

Mystery Person

Default mystery person silhouette

Geometric Pattern

Unique pattern based on email hash

Retro Style

8-bit arcade-style avatar

<GravatarAvatar
  email="user@example.com"
  default="identicon"
  size={80}
/>

Profile Cards

Display complete user profile cards with avatars and information.

Vertical Layout

hello@automattic.com

Profile information unavailable

Horizontal Layout

hello@automattic.com

Profile information unavailable

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

<GravatarProfileCard
  email="user@example.com"
  layout="vertical"
  avatarSize={100}
  showName
  showBio
/>

Custom Styling

Apply custom CSS classes to match your design system.

hello@automattic.com

Profile information unavailable

CSS Example

Create a separate CSS file for your custom styles:

src/styles/gravatar.css

.custom-avatar {
  border: 3px solid #3b82f6;
  box-shadow: 0 4px 6px rgba(59, 130, 246, 0.3);
  transition: transform 0.2s ease;
  border-radius: 50%;
}

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

.custom-card {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  border-radius: 1rem;
  padding: 1.5rem;
}

.custom-card .gravatar-profile-card__name-link,
.custom-card .gravatar-profile-card__name-text {
  color: white;
}

.custom-card .gravatar-profile-card__email {
  color: #e0e7ff;
}

Then import it in your Astro component:

---
import '../styles/gravatar.css';
import GravatarAvatar from 'astro-gravatar';
---

<GravatarAvatar email="user@example.com" size={100} class="custom-avatar" />

QR Code Generation

Generate QR codes that link directly to user Gravatar profiles for easy mobile access.

Basic QR Code

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

<GravatarQR email="user@example.com" size={100} />

Scan to view profile

QR Code with Custom Styling

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

<GravatarQR
  email="user@example.com"
  size={150}
  version={3}
  type="gravatar"
  class="qr-custom"
/>

Scan to view profile

QR Code Collection

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

const team = [
  'alice@example.com',
  'bob@example.com',
  'charlie@example.com'
];
---

<div style="display: flex; gap: 2rem; justify-content: center; margin: 2rem 0;">
  {team.map(email => (
    <div key={email} style="text-align: center;">
      <GravatarQR
        email={email}
        size={100}
        version={3}
        type="user"
      />
      <p style="margin-top: 0.5rem; font-size: 0.9rem;">
        {email.split('@')[0]}
      </p>
    </div>
  ))}
</div>

Best Practices

1. Always provide email addresses - Gravatar requires valid email addresses to generate avatars and QR codes
2. Set reasonable sizes - Keep avatar sizes between 32px and 200px, QR codes between 80-200px for optimal scanning
3. Choose appropriate defaults - Use identicon for consistent patterns or mp for simple silhouettes
4. Handle missing profiles - The profile card gracefully handles users without public Gravatar profiles
5. Consider lazy loading - Use the lazy prop for avatars below the fold
6. Test QR codes - Always test generated QR codes with mobile scanners before deployment

Further Reading

• Read about how-to guides in the Diátaxis framework
• Quick Start Guide - Get started with astro-gravatar
• Component Reference - Complete API documentation
• GravatarQR Reference - QR code component documentation