readme-widgets-kit

Real-time SVG widgets for your GitHub profile README. Spotify, Steam, VS Code, and more — animated, themeable, and embeddable in one line of Markdown.

     

---

Use the Hosted Service (Recommended)

No setup required. Sign in with GitHub, connect your services, and paste the URL into your README — done in under 2 minutes.

→ Get your widgets at widgets.1ceit.com

How it works:

1. Sign in with GitHub at widgets.1ceit.com
2. Connect Spotify, Steam, or your VS Code extension
3. Copy the embed URL for your widget and paste it into your README

![Now Playing](https://widgets.1ceit.com/your-username/spotify)

That's it. The widget updates in real-time — no rebuilds, no cache issues.

---

Widget Catalog

Now Playing — Spotify

Shows your currently playing (or last played) track with album art, progress bar, and animated music bars.

![Now Playing](https://widgets.1ceit.com/{username}/spotify)

<!-- Click the widget to open the track on Spotify -->
[![Now Playing](https://widgets.1ceit.com/{username}/spotify)](https://widgets.1ceit.com/{username}/spotify?open)

Themes: classic · dark · spotify · glass · github-dark · github-light
Layouts: wide (banner) · card (square album art)
→ Full parameter reference

---

Top Artists — Spotify

Your most-listened-to artists over the last 4 weeks, 6 months, or all time.

![Top Artists](https://widgets.1ceit.com/{username}/spotify/top-artists)

Options: 1–5 artists · list or grid layout · short_term / medium_term / long_term
→ Full parameter reference

---

Top Tracks — Spotify

Your most-played tracks with artist names, album art, and optional rankings.

![Top Tracks](https://widgets.1ceit.com/{username}/spotify/top-tracks)

Options: 1–5 tracks · list or grid layout · all three time ranges
→ Full parameter reference

---

Now Coding — VS Code

Shows the file and language you're currently editing, updated live via the VS Code extension.

![Now Coding](https://widgets.1ceit.com/{username}/nowcoding)

Themes: classic · dark · glass · github-dark · github-light · dracula · monokai · tokyo-night · cyberpunk
→ Full parameter reference · VS Code extension setup

---

Now Gaming — Steam

Shows your currently playing game with session timer, playtime, and status badge.

![Now Gaming](https://widgets.1ceit.com/{username}/steam)

Themes: classic · steam-dark · dark · glass · github-dark · github-light
→ Full parameter reference

---

Top Games — Steam

Your most-played Steam games with playtime bars and optional achievement progress.

![Top Games](https://widgets.1ceit.com/{username}/steam/top-games)

Options: 1–5 games · list or grid layout · achievement label (off / percent / count)
→ Full parameter reference

---

Views — Profile Counter

Counts how many times your GitHub README has been viewed via GitHub Camo (the image proxy).

![Views](https://widgets.1ceit.com/{username}/views)

Themes: All 9 themes supported
→ Full parameter reference

---

Themes

All widgets support a theme setting. Pass it via ?settings= — see docs/url-params.md.

Theme	Preview	Works On
classic	White background, Spotify green accent	All widgets
dark	Pure black background	All widgets
spotify	Spotify dark green	Spotify only
glass	Frosted glass (semi-transparent)	All widgets
github-dark	Matches GitHub dark mode (#0D1117)	All widgets
github-light	Matches GitHub light mode (#F6F8FA)	All widgets
steam-dark	Steam's navy blue	Steam widgets
dracula	Dracula color scheme	Coding, Views
monokai	Monokai color scheme	Coding, Views
tokyo-night	Tokyo Night color scheme	Coding, Views
cyberpunk	Dark cyberpunk palette	Coding, Views
custom	Full color control via ?settings=colors	All widgets

→ See docs/themes.md for the full color reference per theme.

---

Static Animated SVG Previews

The previews/ folder contains animated SVG snapshots of every widget in every theme. These include all CSS animations (music bars, pulse effects, scrolling text) and render in GitHub READMEs.

previews/
├── now-playing/
│   ├── classic.svg
│   ├── dark.svg
│   ├── github-dark.svg
│   └── ...
├── top-artists/
├── top-tracks/
├── now-coding/
├── now-gaming/
├── top-games/
└── views/

To regenerate previews (e.g., after a design update):

# Point at your local dev server
node scripts/capture-previews.mjs --base-url http://localhost:3000 --username your-username

# Or regenerate from the hosted service
node scripts/capture-previews.mjs --base-url https://widgets.1ceit.com --username 1ceit

---

Self-Hosting

Want to run your own instance? You can deploy to Vercel in about 10 minutes — no database or Redis required for a single-user setup.

→ Self-Hosting Guide

Quick start:

---

URL Customization

All widget preferences are controlled via the ?settings= query parameter (JSON-encoded). On the hosted service your preferences are saved when you connect. On a self-hosted instance everything goes through the URL.

→ Full reference: docs/url-params.md

---

Copy-Paste Markdown Snippets

→ examples/markdown/ — ready-to-use snippets for every widget with all common options.

---

Contributing

This repo contains the open-source reference, preview assets, and documentation. The main application lives at readme-widgets.

1. Fork the repo
2. Make your changes
3. Run node scripts/capture-previews.mjs to regenerate previews if you changed widget designs
4. Open a pull request

---

License

MIT — see LICENSE.

Built and maintained by @1ceit. Hosted at widgets.1ceit.com.