mintel.me/apps/web/EMBED_USAGE_GUIDE.md

Embed Components Usage Guide

Overview

Your blog now supports rich content embedding from YouTube, Twitter/X, and other platforms with full styling control and build-time generation.

Components Available

1. YouTubeEmbed

Location: src/components/YouTubeEmbed.astro

Features:

• Build-time generation (no client-side API calls)
• Full styling control via CSS variables
• Lazy loading with Intersection Observer
• Multiple style variations
• Responsive aspect ratios

Usage:

---
import YouTubeEmbed from '../components/YouTubeEmbed.astro';
---

<YouTubeEmbed 
  videoId="dQw4w9WgXcQ"
  title="My Video"
  className="my-custom-class"
  aspectRatio="56.25%"
  style="minimal"
/>

Props:

• videoId (required) - YouTube video ID
• title (optional) - Video title for accessibility
• className (optional) - Custom CSS classes
• aspectRatio (optional) - Default "56.25%" (16:9)
• style (optional) - 'default' | 'minimal' | 'rounded' | 'flat'

Styling Control:

/* Override CSS variables */
.youtube-embed {
  --aspect-ratio: 56.25%;
  --bg-color: #000000;
  --border-radius: 8px;
  --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1);
}

/* Use data attributes for variations */
.youtube-embed[data-style="minimal"] { /* ... */ }
.youtube-embed[data-aspect="square"] { /* ... */ }

2. TwitterEmbed

Location: src/components/TwitterEmbed.astro

Features:

• Fetches tweet data at build time using Twitter oEmbed API
• Fallback to simple link if API fails
• Theme support (light/dark)
• Alignment options
• Runtime widget loading for enhanced display

Usage:

---
import TwitterEmbed from '../components/TwitterEmbed.astro';
---

<TwitterEmbed 
  tweetId="1234567890123456789"
  theme="dark"
  className="my-tweet"
  align="center"
/>

Props:

• tweetId (required) - Tweet ID from URL
• theme (optional) - 'light' | 'dark'
• className (optional) - Custom CSS classes
• align (optional) - 'left' | 'center' | 'right'

Note: Requires internet access during build to fetch tweet data.

3. GenericEmbed

Location: src/components/GenericEmbed.astro

Features:

• Universal oEmbed support
• Auto-detects provider
• Fallback for unsupported platforms
• Type-specific styling (video, article, rich)

Usage:

---
import GenericEmbed from '../components/GenericEmbed.astro';
---

<GenericEmbed 
  url="https://vimeo.com/123456789"
  type="video"
  className="my-embed"
  maxWidth="800px"
/>

Props:

• url (required) - Full URL to embed
• type (optional) - 'video' | 'article' | 'rich'
• className (optional) - Custom CSS classes
• maxWidth (optional) - Container max width

Supported Providers:

• YouTube (via oEmbed)
• Vimeo (via oEmbed)
• Twitter/X (via oEmbed)
• CodePen (via oEmbed)
• GitHub Gists (via oEmbed)

Integration Examples

In Blog Posts (src/pages/blog/[slug].astro)

---
import YouTubeEmbed from '../components/YouTubeEmbed.astro';
import TwitterEmbed from '../components/TwitterEmbed.astro';
import GenericEmbed from '../components/GenericEmbed.astro';
---

{post.slug === 'my-post' && (
  <>
    <h2>YouTube Example</h2>
    <YouTubeEmbed videoId="dQw4w9WgXcQ" style="minimal" />
    
    <h2>Twitter Example</h2>
    <TwitterEmbed tweetId="1234567890123456789" theme="dark" />
    
    <h2>Vimeo Example</h2>
    <GenericEmbed url="https://vimeo.com/123456789" type="video" />
  </>
)}

In MDX Content

import { YouTubeEmbed, TwitterEmbed } from '../components/Embeds';

# My Blog Post

Here's a YouTube video:

<YouTubeEmbed videoId="dQw4w9WgXcQ" style="rounded" />

And a tweet:

<TwitterEmbed tweetId="1234567890123456789" />

Custom Styling Examples

Minimal Blog Style

/* In your global.css */
.youtube-embed[data-style="minimal"] {
  --border-radius: 4px;
  --shadow: none;
  --bg-color: #1a1a1a;
}

.twitter-embed {
  --border-radius: 6px;
  --bg-color: #f8fafc;
}

/* Hover effects */
.embed-wrapper:hover {
  transform: translateY(-1px);
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}

Dark Mode Support

/* Dark mode adjustments */
@media (prefers-color-scheme: dark) {
  .youtube-embed {
    --bg-color: #000000;
    --border-color: #334155;
  }
  
  .twitter-embed[data-theme="dark"] {
    --bg-color: #1e293b;
  }
}

Custom Width & Alignment

<YouTubeEmbed 
  videoId="dQw4w9WgXcQ"
  className="max-w-2xl mx-auto"
/>

Performance Benefits

1. Build-Time Generation - All embeds are fetched at build time
2. Zero Client JS - No external API calls on page load
3. Lazy Loading - Iframes load only when visible
4. CDN Compatible - Works with any static hosting
5. SEO Friendly - Static HTML content

Troubleshooting

Twitter Embed Not Loading

• Check internet connection during build
• Verify tweet ID is correct
• Check Twitter API status
• Fallback link will be shown

YouTube Embed Issues

• Verify video ID is correct
• Video must be public/unlisted
• Check iframe restrictions

Generic Embed Failures

• Provider must support oEmbed
• Some providers require authentication
• Fallback to simple link provided

Migration from Paid Services

If you were using services like Embedly or Iframely:

1. Replace imports:

   - import Embedly from 'embedly-react';
   + import YouTubeEmbed from '../components/YouTubeEmbed.astro';
   

2. Update props:

   - <Embedly url={videoUrl} />
   + <YouTubeEmbed videoId="abc123" />
   

3. Customize styling using CSS variables

Next Steps

1. Test components in your development environment
2. Add embeds to existing blog posts
3. Customize styling to match your theme
4. Consider adding more providers (Instagram, TikTok, etc.)

All components are free, self-hosted, and give you complete control over styling and behavior.