# YT Widget

**A self-hostable, HTML-injectable YouTube widget for any website.**  
Drop one `<div>` + one `<script>` tag into any webpage and get a beautiful, responsive YouTube feed — just like SociableKIT, but free and open source.

---

## 🚀 Quick Start

### Step 1 — Get a YouTube API Key (free)

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project (or use an existing one)
3. Navigate to **APIs & Services → Library**
4. Search for and enable **"YouTube Data API v3"**
5. Go to **APIs & Services → Credentials → Create Credentials → API Key**
6. **Restrict your key** to your domain under "Website restrictions" for security

> ⚡ Free tier: 10,000 units/day — each widget page load uses ~3–5 units.

---

### Step 2 — Find Your Channel ID

- Go to **YouTube Studio → Settings → Channel → Advanced settings**  
- Copy the **Channel ID** (starts with `UC`)

Or from any YouTube channel page URL:  
`youtube.com/channel/`**`UCxxxxxxxxxxxxxxxxxxxxxx`**

---

### Step 3 — Add the Widget to Your Page

Copy `yt-widget.js` to your server (or CDN), then paste this into any HTML page:

```html
<!-- Place this where you want the widget to appear -->
<div
  data-yt-widget
  data-channel-id="UCxxxxxxxxxxxxxxxxxxxxxx"
  data-api-key="AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXX"
  data-layout="grid"
  data-theme="dark"
  data-max-results="9">
</div>

<!-- Place this before </body> -->
<script src="/path/to/yt-widget.js"></script>
```

---

## 🎛️ Configuration Options

All options are set via `data-*` attributes on the widget div:

| Attribute | Values | Default | Description |
|-----------|--------|---------|-------------|
| `data-api-key` | string | **required** | YouTube Data API v3 key |
| `data-channel-id` | `UCxxxxx...` | required* | YouTube channel ID |
| `data-video-id` | `xxxxxxxxxxx` | required* | Video ID (for `type=single`) |
| `data-playlist-id` | `PLxxxxx...` | required* | Playlist ID (for `type=playlist`) |
| `data-type` | `feed` \| `stats` \| `single` \| `playlist` | `feed` | Widget display type |
| `data-layout` | `grid` \| `list` | `grid` | Card layout style |
| `data-theme` | `dark` \| `light` | `dark` | Color theme |
| `data-accent-color` | any CSS color | `#ff0033` | Accent / highlight color |
| `data-max-results` | `1`–`50` | `9` | Number of videos to show |
| `data-show-channel-info` | `true` \| `false` | `true` | Show channel header with avatar & subscribe button |

*Required fields depend on widget type.

---

## 🎬 Widget Types

### `feed` — Latest Video Grid/List
Shows the most recent uploads from a channel.
```html
<div data-yt-widget
     data-channel-id="UCxxxxxx"
     data-api-key="YOUR_KEY"
     data-type="feed"
     data-layout="grid"
     data-max-results="9">
</div>
```

### `stats` — Channel Statistics
Shows subscriber count, total views, and video count.
```html
<div data-yt-widget
     data-channel-id="UCxxxxxx"
     data-api-key="YOUR_KEY"
     data-type="stats">
</div>
```

### `single` — Single Video Player
Embeds a specific video with full metadata.
```html
<div data-yt-widget
     data-video-id="dQw4w9WgXcQ"
     data-api-key="YOUR_KEY"
     data-type="single">
</div>
```

### `playlist` — Playlist Grid
Shows videos from a specific playlist.
```html
<div data-yt-widget
     data-channel-id="UCxxxxxx"
     data-playlist-id="PLxxxxxx"
     data-api-key="YOUR_KEY"
     data-type="playlist"
     data-max-results="12">
</div>
```

---

## 🎨 Theming & Customization

### Dark Theme (default)
```html
<div data-yt-widget data-theme="dark" ...></div>
```

### Light Theme
```html
<div data-yt-widget data-theme="light" ...></div>
```

### Custom Accent Color
```html
<div data-yt-widget data-accent-color="#7c3aed" ...></div>
```

### CSS Variable Overrides
After the widget renders, you can override any CSS variable on the root element:
```css
#my-widget { --ytw-radius: 8px; --ytw-bg: transparent; }
```

---

## 📦 Multiple Widgets on One Page

You can place multiple `data-yt-widget` divs on the same page — they all initialize independently:

```html
<!-- Feed widget -->
<div data-yt-widget data-channel-id="UC111" data-api-key="KEY" data-type="feed"></div>

<!-- Stats widget for a different channel -->
<div data-yt-widget data-channel-id="UC222" data-api-key="KEY" data-type="stats"></div>
```

---

## 🔧 JavaScript API

The widget exposes a global `YTWidget` object:

```javascript
// Re-initialize all widgets on the page (useful after dynamic DOM changes)
YTWidget.reinit();

// Initialize a specific element manually
const el = document.querySelector('#my-widget');
YTWidget.init(el);

// Get the version
console.log(YTWidget.version); // "1.0.0"
```

---

## 🗂️ File Structure

```
yt-widget/
├── yt-widget.js     ← The injectable widget script (copy this to your server)
├── index.html       ← Visual builder/preview dashboard
├── demo.html        ← Sample customer site with embedded widget
├── styles.css       ← Builder dashboard styles (not needed for the widget)
└── README.md        ← This file
```

> **To deploy**: Only `yt-widget.js` needs to be on your server/CDN. The other files are for development and building purposes.

---

## ⚠️ Important Notes

### API Key Security
- The API key is **client-side** (visible in page source), which is standard for all similar services
- **Always restrict your key** in Google Cloud Console to specific HTTP referrers (your domain)
- Monitor usage in the Cloud Console to detect abuse

### API Quota
- YouTube Data API v3 free tier: **10,000 units/day**
- Each widget initialization costs approximately:
  - Feed widget: ~4 units (channels.list + playlistItems.list + videos.list)
  - Stats widget: ~1 unit (channels.list)
  - Single video: ~1 unit (videos.list)
- For high-traffic sites, consider implementing server-side caching

### CORS
- The YouTube API supports CORS, so client-side `fetch()` requests work without a backend

---

## 📄 License

MIT License — free for personal and commercial use.

---

## 🔗 Links

- [YouTube Data API v3 Documentation](https://developers.google.com/youtube/v3)
- [Google Cloud Console](https://console.cloud.google.com/)
- [YouTube Studio](https://studio.youtube.com/)
- [Builder Dashboard](index.html)