Beautiful README badges.
A shields.io alternative styled as shadcn/ui buttons. Never paywalled.
Homepage · Docs · CLI · API Reference · 𝕏
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.
Generate badges from your terminal:
# Scan current repo and generate badge markdown
npx shieldcn-cli
# Scan a GitHub repo
npx shieldcn-cli vercel/next.js --variant branded
# Inject badges into README
npx shieldcn-cli --inject
# Migrate shields.io URLs to shieldcn
npx shieldcn-cli migrateSee the CLI docs for full usage.
Combine multiple badges into a single joined image — like a shadcn ButtonGroup:
Join any badge paths with + under /group/. Query params apply to all segments. See the Badge Group docs.
See the docs for full endpoint details, interactive sandboxes, and copy-paste examples.
| 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, downloads | /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} |
| Conda | version, downloads, platform | /conda/v/{channel}/{package} |
| jsDelivr | CDN hits, rank | /jsdelivr/hits/npm/{package} |
| Chocolatey | version, downloads | /chocolatey/v/{package} |
| Snapcraft | version | /snapcraft/v/{snap} |
| Provider | Badges | Endpoint |
|---|---|---|
| GitHub | stars, forks, watchers, license, release, CI, checks, issues, PRs, milestones, commits, downloads (all/specific asset, all/latest/tag), dependabot, and more | /github/{owner}/{repo}/{topic} |
| GitLab | stars, forks, issues, pipeline, license, release, contributors | /gitlab/{owner}/{repo}/{topic} |
| Codecov | coverage percentage (color-coded) | /codecov/{service}/{owner}/{repo} |
| Coveralls | coverage percentage (color-coded) | /coveralls/{service}/{owner}/{repo} |
| SonarCloud | quality gate, bugs, vulnerabilities, coverage, maintainability, reliability, security | /sonar/{topic}/{component} |
| VS Code Marketplace | installs, rating, version | /vscode/installs/{publisher}/{extension} |
| Open VSX | version, downloads, rating | /openvsx/v/{namespace}/{extension} |
| Provider | Badges | Endpoint |
|---|---|---|
| Chrome Web Store | version, users, rating | /chrome/v/{extensionId} |
| Mozilla Add-ons | version, users, rating, downloads | /amo/v/{slug} |
| Flathub | version, downloads | /flathub/v/{appId} |
| F-Droid | version | /fdroid/v/{appId} |
| Provider | Badges | Endpoint |
|---|---|---|
| Discord | online count, members | /discord/{serverId} |
| karma, subscribers | /reddit/subscribers/r/{subreddit} |
|
| Bluesky | followers, following, posts | /bluesky/{handle} |
| X / Twitter | follow CTA, mention CTA | /x/follow/{username} |
| 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} |
| Discourse | topics, posts, users, likes | /discourse/topics/{server} |
| Matrix | room members | /matrix/members/{roomAlias} |
| Stack Exchange | tag questions, user reputation | /stackexchange/tag/{tag} |
| Provider | Badges | Endpoint |
|---|---|---|
| Open Collective | backers, sponsors, contributors, balance, budget | /opencollective/backers/{slug} |
| Liberapay | receiving, patrons, goal | /liberapay/receiving/{username} |
| WakaTime | coding time | /wakatime/{username} |
| Weblate | translation %, language count | /weblate/translation/{server}/{project}/{component} |
| Modrinth | downloads, followers, version, game versions | /modrinth/downloads/{slug} |
| Tokscale | tokens, cost, rank, active days | /tokscale/{username} |
| Type | Description | Endpoint |
|---|---|---|
| Badge Group | Multiple badges joined in one image | /group/{badge1}+{badge2}+{badge3} |
| 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} |
Every badge supports shadcn Button variants and sizes:
Three icon libraries (40,000+ icons) plus custom SVG upload:
- Simple Icons —
?logo=react - React Icons —
?logo=ri:GoStarFill - 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
.png— PNG image (recommended for GitHub READMEs and maximum compatibility).svg— SVG image (scalable, smaller file size).json— raw badge data/shields.json— shields.io-compatible endpoint
Both .png and .svg work everywhere GitHub renders images. Just swap the extension.
- 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
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/shieldcnOnce 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.
Run your own badge engine with Docker:
git clone https://github.com/jal-co/shieldcn.git
cd shieldcn
docker compose -f packages/engine/docker-compose.yml up -d
# Test it
curl http://localhost:3000/badge/self--hosted-green.svgOr pull the pre-built image:
docker pull ghcr.io/jal-co/shieldcn/engine:latestSee the Self-Hosting Guide for full setup details.
pnpm install # install all workspace deps
pnpm dev:web # start the web site
pnpm dev:engine # start the self-hosted engine
pnpm build:web # build the web site
pnpm build:engine # build the engineThe repo is a Turborepo monorepo with three packages:
packages/core— shared badge engine librarypackages/web— marketing site (Vercel)packages/engine— self-hosted Docker image
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.
- 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.
PRs welcome. See AGENTS.md for architecture overview.
To add shadcn components: cd packages/web && pnpm dlx shadcn@latest add {component}
