gian-gg/icon-marquee

Dynamic SVG icon marquees for READMEs, portfolios, and web pages

Summary

icon-marquee is a hosted service that turns a list of tech icon names into a scrolling or static SVG, returned as an image you can drop into any page with a plain <img> tag. The output is SVG with CSS animation, so it stays sharp at any size, ships no JavaScript, and renders correctly inside GitHub READMEs. Icons come from the skills-icons set, with short aliases such as js or ts, and themed icons switch with the viewer's system light/dark setting.

What it is useful for

The service is useful for showing a stack or skill list in a README header, portfolio page, or any static site that needs a self-contained, no-build, lightweight image. The marquee endpoint suits banners that scroll a moving row of technologies, while the icons endpoint suits a clean static row. Because the result is an embeddable SVG, it works on GitHub, static sites, and any context that supports a standard image tag, without bundlers or a runtime library.

How engineers can use it

Three endpoints are documented in the README:

• GET /v1/marquee?i=... — animated SVG that scrolls left at 30px/s, stops for viewers with prefers-reduced-motion: reduce, and loops eight icons roughly every 15 seconds.
• GET /v1/icons?i=... — the same icons in a static row, in the order listed.
• GET /v1 — health check returning {"status":"ok"}.

A Markdown usage example from the README:

![my stack](https://icon-marquee.giann.dev/v1/marquee?i=js,ts,react,docker)

The i parameter takes comma-separated names or short aliases, and the width parameter (1–3840) sets the window for the marquee, with the row repeated to fill it. Documented constraints: at most 100 icons per request, the default visible window is at most 400px wide, unknown names are skipped and reported in the X-Unknown-Icons response header, and a request where every name is unknown returns HTTP 400. The icon set contains 1041 names, 767 of them themed.

For self-hosting, the README requires Bun and documents:

bun install
cp .env.example .env   # then set APP_NAME
bun dev                # http://localhost:3000/v1/marquee?i=js,ts

APP_NAME is required and the server refuses to start without it. The README also documents bun test, bun run typecheck, and bun run check (Biome lint/format/imports sort). The project is MIT licensed, and the underlying icons are credited to skills-icons by Syvixor.