shieldcn-badges

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

[![alt](https://shieldcn.dev/{provider}/{params}.svg)](https://link)

<!-- or without link -->
![alt](https://shieldcn.dev/{provider}/{params}.svg)

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)

![badge](https://shieldcn.dev/npm/react.svg?variant=secondary)

Branded variant (brand-colored bg)

![badge](https://shieldcn.dev/npm/react.svg?variant=branded)

Split badge (two-tone)

![badge](https://shieldcn.dev/npm/react.svg?split=true)

Light mode

![badge](https://shieldcn.dev/npm/react.svg?mode=light)

Custom icon

![badge](https://shieldcn.dev/npm/react.svg?logo=typescript)
![badge](https://shieldcn.dev/github/stars/owner/repo.svg?logo=ri:GoStarFill)

No icon

![badge](https://shieldcn.dev/npm/react.svg?logo=false)

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: ![stars](https://shieldcn.dev/chart/github/stars/vercel/next.js.svg)

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

1. Always use .svg for markdown images (best quality, smallest size)
2. Use <a> wrapper to make badges clickable links
3. Use <p align="center"> to center badge rows in GitHub READMEs
4. Replace {owner}, {repo}, {package} with actual values — never leave placeholders
5. Default variant (default) works on both light and dark GitHub themes
6. Icons are auto-resolved per provider — only set ?logo= to override
7. For npm scoped packages, use the full scope: /npm/v/@scope/package
8. Prefer variant=secondary for subtle badge rows
9. Keep badge rows to 3–6 badges for readability
10. 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