Beautiful README badges.
A shields.io alternative styled as shadcn/ui buttons. Never paywalled.
Homepage · Docs · API Reference
About
shieldcn is an open-source badge service by Justin Levine. Every badge is free, every endpoint is public, and that's not changing.
Badges are rendered as actual shadcn/ui Button components via Satori — same font (Inter), same border-radius, same padding, same color tokens per variant and size. Not "inspired by" — the real thing, as SVG.
Built with jal-co/ui components.
Usage
    
Supported providers
See the docs for full endpoint details, interactive sandboxes, and copy-paste examples.
Package registries
| Provider | Badges | Endpoint |
|---|---|---|
| npm | version, downloads, license, node, types, dependents | /npm/{package} |
| PyPI | version, downloads, license, python version | /pypi/{package} |
| Crates.io | version, downloads, license | /crates/{crate} |
| Docker Hub | pulls, stars, version, image size | /docker/pulls/{image} |
| Packagist | version, downloads, license | /packagist/v/{vendor}/{package} |
| RubyGems | version, downloads, license | /rubygems/{gem} |
| NuGet | version, downloads | /nuget/{package} |
| Pub.dev | version, likes, points, popularity | /pub/{package} |
| Homebrew | version (formula + cask), installs | /homebrew/{formula} |
| Maven Central | version | /maven/{groupId}/{artifactId} |
| CocoaPods | version | /cocoapods/{pod} |
| JSR | version, score | /jsr/{@scope}/{name} |
| Bundlephobia | min size, minzip size, tree-shaking | /bundlephobia/minzip/{package} |
Code platforms
| Provider | Badges | Endpoint |
|---|---|---|
| GitHub | stars, forks, watchers, license, release, CI, checks, issues, PRs, milestones, commits, downloads, dependabot, and more | /github/{owner}/{repo}/{topic} |
| Codecov | coverage percentage (color-coded) | /codecov/{service}/{owner}/{repo} |
| VS Code Marketplace | installs, rating, version | /vscode/installs/{publisher}/{extension} |
Social
| Provider | Badges | Endpoint |
|---|---|---|
| Discord | online count, members | /discord/{serverId} |
| karma, subscribers | /reddit/subscribers/r/{subreddit} |
|
| Bluesky | followers, following, posts | /bluesky/{handle} |
| YouTube | subscribers, channel views, video views, likes, comments | /youtube/subscribers/{channelId} |
| Mastodon | followers, following, posts | /mastodon/followers/{instance}/{acct} |
| Lemmy | subscribers, posts, comments | /lemmy/subscribers/{instance}/{community} |
| Hacker News | karma | /hackernews/{userId} |
| Twitch | live status, followers | /twitch/status/{login} |
Funding & Tools
| Provider | Badges | Endpoint |
|---|---|---|
| Open Collective | backers, sponsors, contributors, balance, budget | /opencollective/backers/{slug} |
| WakaTime | coding time | /wakatime/{username} |
Custom badges
| Type | Description | Endpoint |
|---|---|---|
| Static | Custom label/message/color | /badge/{label}-{message}-{color} |
| Dynamic JSON | Fetch any JSON API | /badge/dynamic/json?url=...&query=... |
| HTTPS Endpoint | Proxy any JSON endpoint | /https/{hostname}/{path} |
| Memo | User-stored badges (PUT API) | /memo/{key} |
Variants & sizes
Every badge supports shadcn Button variants and sizes:
         
Icons
Three icon libraries (40,000+ icons) plus custom SVG upload:
- Simple Icons —
?logo=react - Lucide —
?logo=lucide:star - React Icons —
?logo=ri:FaReact - Custom SVG —
?logo=data:image/svg+xml;base64,...— upload any SVG icon via the Badge Builder or encode it yourself
Response formats
.svg— SVG image (default, for READMEs and docs).png— rasterized PNG.json— raw badge data/shields.json— shields.io-compatible endpoint
Design principles
- shadcn buttons, not shields.io rectangles — badges are rendered as actual shadcn Button components with real Inter font outlines via Satori
- Everything configurable — variant, size, mode, colors, icons, opacity, split, dot — but sensible defaults so you don't have to configure anything
- Shields.io compatible — same URL patterns for static/dynamic badges, same text encoding, shields.io JSON endpoint support
- Open source, never paywalled — every badge type, every variant, every icon source is free
Agent skill
Install the shieldcn skill to let AI coding agents (Claude Code, Cursor, Codex, and 40+ more) add badges to your projects:
npx skills add jal-co/shieldcn
Once installed, ask your agent to "add shieldcn badges to the README" — it knows all providers, URL patterns, and query parameters.
Learn more in the skill docs.
Local development
pnpm install # install dependencies pnpm dev # start dev server pnpm build # next build
Token pool
shieldcn uses a token pool (inspired by shields.io) to distribute GitHub API requests across many tokens. You can help by authorizing the OAuth app — read-only, zero scopes, revocable anytime.
Credits
- shields.io — the original badge service. Inspiration for URL patterns, static badge format, and the token pool system.
- badgen.net — inspiration for many badge types and endpoint structures, especially the GitHub badge coverage.
- shadcn/ui — the design system these badges are built on.
- Satori — Vercel's JSX-to-SVG engine that makes rendering React components as badge images possible.
- jal-co/ui — the component library powering the docs site.
- @k33bs — creator of shieldcngen, the badge generator tool powering the
/genpage.
Contributing
PRs welcome. See AGENTS.md for architecture overview.