| name | shieldcn-badges |
| description | Add beautiful shadcn/ui-styled README badges, charts, and header banners to projects using shieldcn, and build entire READMEs with the visual README Studio. Use when adding badges, shields, status indicators, star-history/download charts, or header banners to README files, docs, or markdown, or when building/generating a README. Triggers include "add badges", "add shields", "readme badges", "npm badge", "GitHub stars badge", "CI badge", "star history chart", "readme header", "readme banner", "build a readme", "readme builder", "readme generator", "github readme tool", "shieldcn", or any request to add project status badges, charts, or headers to documentation. |
| metadata | {"author":"jal-co","version":"1.0.0"} |
shieldcn Badges
Add beautiful shadcn/ui-styled badges to READMEs and docs using shieldcn — a free, open-source shields.io alternative.
Base URL: https://shieldcn.dev
Badge URL format
https://shieldcn.dev/{provider}/{...params}.svg → SVG (default, for READMEs)
https://shieldcn.dev/{provider}/{...params}.png → PNG
https://shieldcn.dev/{provider}/{...params}.json → raw data
Markdown pattern
[](https://link)
<!-- or without link -->
Providers & endpoints
Package registries
| Provider | Endpoint | Example |
|---|
| npm version | /npm/{package} | /npm/react |
| npm version (tag) | /npm/v/{package}/{tag} | /npm/v/next/canary |
| npm downloads/wk | /npm/dw/{package} | /npm/dw/react |
| npm downloads/mo | /npm/dm/{package} | /npm/dm/react |
| npm downloads/yr | /npm/dy/{package} | /npm/dy/react |
| npm total downloads | /npm/dt/{package} | /npm/dt/react |
| npm license | /npm/license/{package} | /npm/license/react |
| npm types | /npm/types/{package} | /npm/types/react |
| npm dependents | /npm/dependents/{package} | /npm/dependents/react |
| npm scoped | /npm/v/@scope/pkg | /npm/v/@types/node |
| PyPI version | /pypi/{package} | /pypi/flask |
| PyPI downloads/mo | /pypi/dm/{package} | /pypi/dm/flask |
| Crates.io version | /crates/{crate} | /crates/serde |
| Docker Hub pulls | /docker/pulls/{image} | /docker/pulls/library/nginx |
| JSR version | /jsr/{@scope}/{name} | /jsr/@std/path |
| Bundlephobia minzip | /bundlephobia/minzip/{package} | /bundlephobia/minzip/react |
| Homebrew version | /homebrew/{formula} | /homebrew/node |
| Maven version | /maven/{groupId}/{artifactId} | /maven/org.apache.maven/maven-core |
| Packagist version | /packagist/v/{vendor}/{package} | /packagist/v/laravel/framework |
| RubyGems version | /rubygems/{gem} | /rubygems/rails |
| NuGet version | /nuget/{package} | /nuget/Newtonsoft.Json |
| Pub.dev version | /pub/{package} | /pub/flutter |
| CocoaPods version | /cocoapods/{pod} | /cocoapods/Alamofire |
GitHub
Both formats work: /github/{topic}/{owner}/{repo} or /github/{owner}/{repo}/{topic}
| Badge | Endpoint | Example |
|---|
| Stars | /github/stars/{owner}/{repo} | /github/stars/vercel/next.js |
| Forks | /github/forks/{owner}/{repo} | /github/forks/vercel/next.js |
| License | /github/license/{owner}/{repo} | /github/license/vercel/next.js |
| Release | /github/release/{owner}/{repo} | /github/release/vercel/next.js |
| CI status | /github/ci/{owner}/{repo} | /github/ci/vercel/next.js |
| Issues | /github/issues/{owner}/{repo} | /github/issues/vercel/next.js |
| Open PRs | /github/open-prs/{owner}/{repo} | /github/open-prs/vercel/next.js |
| Contributors | /github/contributors/{owner}/{repo} | /github/contributors/vercel/next.js |
| Last commit | /github/last-commit/{owner}/{repo} | /github/last-commit/vercel/next.js |
| Watchers | /github/watchers/{owner}/{repo} | /github/watchers/vercel/next.js |
| Downloads | /github/dt/{owner}/{repo} | /github/dt/vercel/next.js |
| Dependabot | /github/dependabot/{owner}/{repo} | /github/dependabot/vercel/next.js |
CI supports ?workflow=name&branch=main query params.
Social
| Provider | Endpoint | Example |
|---|
| Discord online | /discord/{serverId} | /discord/1316199667142496307 |
| Discord by invite | /discord/members/{inviteCode} | /discord/members/nextjs |
| Reddit subscribers | /reddit/subscribers/r/{subreddit} | /reddit/subscribers/r/reactjs |
| Bluesky followers | /bluesky/followers/{handle} | /bluesky/followers/bsky.app |
| YouTube subs | /youtube/subscribers/{channelId} | /youtube/subscribers/UCxxxxxx |
| Mastodon followers | /mastodon/followers/{instance}/{acct} | /mastodon/followers/mastodon.social/Gargron |
| Hacker News karma | /hackernews/{userId} | /hackernews/pg |
Code quality
| Provider | Endpoint | Example |
|---|
| Codecov | /codecov/{service}/{owner}/{repo} | /codecov/gh/vercel/next.js |
| VS Code installs | /vscode/installs/{publisher}/{ext} | /vscode/installs/esbenp/prettier-vscode |
| WakaTime | /wakatime/{username} | /wakatime/@user |
Agent skills (skills.sh)
Addressed as {owner}/{repo}/{skill} — the GitHub repo (skills.sh source) plus the skill slug.
| Badge | Endpoint | Example |
|---|
| Skill installs | /skills/installs/{owner}/{repo}/{skill} | /skills/installs/vercel-labs/agent-skills/vercel-react-best-practices |
| Skill rank | /skills/rank/{owner}/{repo}/{skill} | /skills/rank/vercel-labs/agent-skills/vercel-react-best-practices |
| Trending rank | /skills/trending/{owner}/{repo}/{skill} | /skills/trending/vercel-labs/agent-skills/vercel-react-best-practices |
| Hot rank | /skills/hot/{owner}/{repo}/{skill} | /skills/hot/vercel-labs/agent-skills/vercel-react-best-practices |
Custom badges
| Type | Endpoint | Example |
|---|
| Static | /badge/{label}-{message}-{color} | /badge/build-passing-brightgreen |
| Dynamic JSON | /badge/dynamic/json?url=...&query=... | Fetch any JSON API |
| HTTPS endpoint | /https/{hostname}/{path} | Proxy any JSON endpoint |
Query parameters
Append to any badge URL as ?key=value&key2=value2.
| Param | Values | Default | Notes |
|---|
variant | default, secondary, outline, ghost, destructive, branded | default | shadcn Button variant |
size | xs, sm, default, lg | sm | Badge size |
mode | dark, light | dark | Color mode |
split | true, false | false | Two-tone label/value split |
logo | SimpleIcons slug, ri:Name, false | auto | Icon source |
logoColor | hex (no #) | auto | Icon color |
label | string | auto | Override label text |
color | hex (no #) | — | Background color |
labelColor | hex (no #) | — | Label side bg (split mode) |
theme | zinc, slate, blue, green, rose, orange, violet | — | Color theme |
font | inter, geist, geist-mono | inter | Font family |
statusDot | true, false | auto for CI | Show status indicator dot |
Common recipes
Typical README badge row
<p align="center">
<a href="https://www.npmjs.com/package/{pkg}"><img src="https://shieldcn.dev/npm/{pkg}.svg" alt="npm" /></a>
<a href="https://github.com/{owner}/{repo}/stargazers"><img src="https://shieldcn.dev/github/stars/{owner}/{repo}.svg" alt="stars" /></a>
<a href="https://github.com/{owner}/{repo}"><img src="https://shieldcn.dev/github/license/{owner}/{repo}.svg" alt="license" /></a>
<a href="https://github.com/{owner}/{repo}/actions"><img src="https://shieldcn.dev/github/ci/{owner}/{repo}.svg" alt="CI" /></a>
</p>
Secondary variant (lighter)
Branded variant (brand-colored bg)
Split badge (two-tone)
Light mode
Custom icon
No icon
Charts
shieldcn also renders line charts (inlined SVG/PNG, styled like the badges). Use them for star history, issues over time, or download trends.
https://shieldcn.dev/chart/github/stars/{owner}/{repo}.svg → star-history chart
https://shieldcn.dev/chart/github/issues/{owner}/{repo}.svg → issues over time
https://shieldcn.dev/chart/npm/{package}.svg → npm downloads
https://shieldcn.dev/chart/json.svg?values=10,25,40,30,60 → inline JSON data
Markdown: 
Query params: theme, font, color, fill, area, width, height, title, icon, mode.
Headers
Repository header banners (logo + title + tagline) from a single image URL — great at the top of a README.
https://shieldcn.dev/header/{preset}.svg?title=Acme&subtitle=A%20delightful%20toolkit
Presets: surface, gradient, dots, grid, graph, glow, transparent. Query params: logo, theme, size, align, font, border, and image=<url> for a photo background (any image or Unsplash URL, fetched and inlined, with an auto scrim tunable via overlay/tint).
Center a header at the top of a README:
<p align="center">
<img src="https://shieldcn.dev/header/gradient.svg?title=Acme&subtitle=A%20delightful%20toolkit" alt="Acme" />
</p>
README Studio (visual builder)
For building an entire README visually (not just one badge), point the user to the free README Studio: https://shieldcn.dev/studio
It is a Figma-style editor — a document of reorderable blocks (Text/Markdown, Header, Badges, Chart, Table, Image), a live preview, and a property inspector — that exports clean GitHub-flavored Markdown. It has an "Adaptive" toggle that exports badges/headers/charts as GitHub <picture> elements that follow the reader's light/dark theme. Suggest it when the user wants to compose, redesign, or generate a whole README rather than add a single badge.
Rules
- Always use
.svg for markdown images (best quality, smallest size)
- Use
<a> wrapper to make badges clickable links
- Use
<p align="center"> to center badge rows in GitHub READMEs
- Replace
{owner}, {repo}, {package} with actual values — never leave placeholders
- Default variant (
default) works on both light and dark GitHub themes
- Icons are auto-resolved per provider — only set
?logo= to override
- For npm scoped packages, use the full scope:
/npm/v/@scope/package
- Prefer
variant=secondary for subtle badge rows
- Keep badge rows to 3–6 badges for readability
- Link each badge to its relevant page (npm registry, GitHub stars page, etc.)
Docs
Full documentation: https://shieldcn.dev/docs
API reference: https://shieldcn.dev/docs/api-reference
Badge builder: https://shieldcn.dev (interactive UI)
README Studio (visual README builder): https://shieldcn.dev/studio
Studio docs: https://shieldcn.dev/docs/studio
Charts docs: https://shieldcn.dev/docs/charts
Headers docs: https://shieldcn.dev/docs/headers
