git:20260507.e08b367 to git:20260622.473e5b3

# shieldcn

> Beautiful README badges. A shields.io alternative styled as shadcn/ui buttons.

shieldcn is a free, open-source badge image service at https://shieldcn.dev. It renders SVG and PNG badge images that look like shadcn/ui Button components — same Inter font, border-radius, padding, and color tokens. Badges are rendered via Satori (JSX → SVG). Use them in GitHub READMEs, npm pages, docs sites, and anywhere that accepts `<img>` tags.

No configuration, no API keys, no build step. Every endpoint is public and free.

## URL format

```

https://shieldcn.dev/{provider}/{...params}.svg → SVG badge

https://shieldcn.dev/{provider}/{...params}.png → PNG badge

https://shieldcn.dev/{provider}/{...params}.json → raw data

https://shieldcn.dev/{provider}/{...params}/shields.json → shields.io compatible

```

## Badge types

### npm

| Badge | URL |

|-------|-----|

| Version | `/npm/{package}.svg` |

| Version (tag) | `/npm/v/{package}[/{tag}].svg` |

| Downloads (weekly) | `/npm/dw/{package}.svg` |

| Downloads (monthly) | `/npm/dm/{package}.svg` |

| Downloads (yearly) | `/npm/dy/{package}.svg` |

| Downloads (total) | `/npm/dt/{package}.svg` |

| License | `/npm/license/{package}.svg` |

| Node version | `/npm/node/{package}.svg` |

| TypeScript types | `/npm/types/{package}.svg` |

| Dependents | `/npm/dependents/{package}.svg` |

Scoped packages: `/npm/@scope/package.svg`

### GitHub

| Badge | URL |

|-------|-----|

| Stars | `/github/stars/{owner}/{repo}.svg` |

| Forks | `/github/forks/{owner}/{repo}.svg` |

| Watchers | `/github/watchers/{owner}/{repo}.svg` |

| Branches | `/github/branches/{owner}/{repo}.svg` |

| Releases | `/github/releases/{owner}/{repo}.svg` |

| Tags | `/github/tags/{owner}/{repo}.svg` |

| Latest tag | `/github/tag/{owner}/{repo}.svg` |

| License | `/github/license/{owner}/{repo}.svg` |

| Release | `/github/release/{owner}/{repo}[/stable].svg` |

| Contributors | `/github/contributors/{owner}/{repo}.svg` |

| CI status | `/github/ci/{owner}/{repo}.svg` |

| Checks | `/github/checks/{owner}/{repo}[/ref][/check].svg` |

| Issues | `/github/issues/{owner}/{repo}.svg` |

| Open issues | `/github/open-issues/{owner}/{repo}.svg` |

| Closed issues | `/github/closed-issues/{owner}/{repo}.svg` |

| Label issues | `/github/label-issues/{owner}/{repo}/{label}[/state].svg` |

| PRs | `/github/prs/{owner}/{repo}.svg` |

| Open PRs | `/github/open-prs/{owner}/{repo}.svg` |

| Closed PRs | `/github/closed-prs/{owner}/{repo}.svg` |

| Merged PRs | `/github/merged-prs/{owner}/{repo}.svg` |

| Milestones | `/github/milestones/{owner}/{repo}/{number}.svg` |

| Commits | `/github/commits/{owner}/{repo}[/ref].svg` |

| Last commit | `/github/last-commit/{owner}/{repo}[/ref].svg` |

| Asset downloads | `/github/assets-dl/{owner}/{repo}[/tag].svg` |

| Downloads (all) | `/github/downloads/{owner}/{repo}[/latest|tag].svg` |

| Downloads (asset) | `/github/downloads-asset/{owner}/{repo}/{asset}[/latest|tag].svg` |

| Dependabot | `/github/dependabot/{owner}/{repo}.svg` |

| Followers | `/github/followers/{username}.svg` |

| User stars | `/github/user-stars/{username}.svg` |

GitHub badges support both URL formats:

- `/github/stars/{owner}/{repo}.svg`

- `/github/{owner}/{repo}/stars.svg`

### GitLab

| Badge | URL |

|-------|-----|

| Stars | `/gitlab/{owner}/{repo}/stars.svg` |

| Forks | `/gitlab/{owner}/{repo}/forks.svg` |

| Issues | `/gitlab/{owner}/{repo}/issues.svg` |

| Open issues | `/gitlab/{owner}/{repo}/open-issues.svg` |

| Closed issues | `/gitlab/{owner}/{repo}/closed-issues.svg` |

| Pipeline | `/gitlab/{owner}/{repo}/pipeline.svg` |

| License | `/gitlab/{owner}/{repo}/license.svg` |

| Last commit | `/gitlab/{owner}/{repo}/last-commit.svg` |

| Contributors | `/gitlab/{owner}/{repo}/contributors.svg` |

| Release | `/gitlab/{owner}/{repo}/release.svg` |

Pipeline supports `?branch=` query param.

### Discord

| Badge | URL |

|-------|-----|

| Online count | `/discord/{serverId}.svg` |

| Members | `/discord/members/{inviteCode}.svg` |

| Online members | `/discord/online-members/{inviteCode}.svg` |

### Reddit

| Badge | URL |

|-------|-----|

| Karma | `/reddit/{type}/u/{user}.svg` |

| Subscribers | `/reddit/subscribers/r/{subreddit}.svg` |

### PyPI

| Badge | URL |

|-------|-----|

| Version | `/pypi/{package}.svg` or `/pypi/v/{package}.svg` |

| Downloads (daily) | `/pypi/dd/{package}.svg` |

| Downloads (weekly) | `/pypi/dw/{package}.svg` |

| Downloads (monthly) | `/pypi/dm/{package}.svg` |

| License | `/pypi/license/{package}.svg` |

| Python version | `/pypi/python/{package}.svg` |

### Crates.io

| Badge | URL |

|-------|-----|

| Version | `/crates/{crate}.svg` or `/crates/v/{crate}.svg` |

| Downloads (total) | `/crates/d/{crate}.svg` |

| Downloads (recent) | `/crates/dr/{crate}.svg` |

| License | `/crates/license/{crate}.svg` |

### Docker Hub

| Badge | URL |

|-------|-----|

| Pulls | `/docker/pulls/{image}.svg` |

| Stars | `/docker/stars/{image}.svg` |

| Version | `/docker/v/{image}.svg` |

| Size | `/docker/size/{image}.svg` |

Image format: `library/nginx` or `grafana/grafana`.

### Bluesky

| Badge | URL |

|-------|-----|

| Followers | `/bluesky/followers/{handle}.svg` |

| Following | `/bluesky/following/{handle}.svg` |

| Posts | `/bluesky/posts/{handle}.svg` |

Default (no topic): `/bluesky/{handle}.svg` → followers.

### JSR

| Badge | URL |

|-------|-----|

| Version | `/jsr/v/{@scope}/{name}.svg` |

| Score | `/jsr/score/{@scope}/{name}.svg` |

Default: `/jsr/{@scope}/{name}.svg` → version.

### Bundlephobia

| Badge | URL |

|-------|-----|

| Minified | `/bundlephobia/min/{package}.svg` |

| Minified + gzip | `/bundlephobia/minzip/{package}.svg` |

| Tree-shaking | `/bundlephobia/tree-shaking/{package}.svg` |

### YouTube

| Badge | URL |

|-------|-----|

| Subscribers | `/youtube/subscribers/{channelId}.svg` |

| Channel views | `/youtube/channel-views/{channelId}.svg` |

| Video views | `/youtube/views/{videoId}.svg` |

| Likes | `/youtube/likes/{videoId}.svg` |

| Comments | `/youtube/comments/{videoId}.svg` |

### VS Code Marketplace

| Badge | URL |

|-------|-----|

| Installs | `/vscode/installs/{publisher}/{extension}.svg` |

| Rating | `/vscode/rating/{publisher}/{extension}.svg` |

| Version | `/vscode/v/{publisher}/{extension}.svg` |

### Open Collective

| Badge | URL |

|-------|-----|

| Backers | `/opencollective/backers/{slug}.svg` |

| Sponsors | `/opencollective/sponsors/{slug}.svg` |

| Contributors | `/opencollective/contributors/{slug}.svg` |

| Balance | `/opencollective/balance/{slug}.svg` |

| Budget | `/opencollective/budget/{slug}.svg` |

### Hacker News

| Badge | URL |

|-------|-----|

| Karma | `/hackernews/{userId}.svg` or `/hackernews/karma/{userId}.svg` |

### Mastodon

| Badge | URL |

|-------|-----|

| Followers | `/mastodon/followers/{instance}/{acct}.svg` |

| Following | `/mastodon/following/{instance}/{acct}.svg` |

| Posts | `/mastodon/posts/{instance}/{acct}.svg` |

### Lemmy

| Badge | URL |

|-------|-----|

| Subscribers | `/lemmy/subscribers/{instance}/{community}.svg` |

| Posts | `/lemmy/posts/{instance}/{community}.svg` |

| Comments | `/lemmy/comments/{instance}/{community}.svg` |

### Packagist

| Badge | URL |

|-------|-----|

| Version | `/packagist/v/{vendor}/{package}.svg` |

| Downloads (total) | `/packagist/dt/{vendor}/{package}.svg` |

| Downloads (monthly) | `/packagist/dm/{vendor}/{package}.svg` |

| Downloads (daily) | `/packagist/dd/{vendor}/{package}.svg` |

| License | `/packagist/license/{vendor}/{package}.svg` |

### RubyGems

| Badge | URL |

|-------|-----|

| Version | `/rubygems/v/{gem}.svg` |

| Downloads (total) | `/rubygems/dt/{gem}.svg` |

| Downloads (version) | `/rubygems/dv/{gem}.svg` |

| License | `/rubygems/license/{gem}.svg` |

### NuGet

| Badge | URL |

|-------|-----|

| Version | `/nuget/v/{package}.svg` |

| Downloads | `/nuget/dt/{package}.svg` |

### Pub.dev

| Badge | URL |

|-------|-----|

| Version | `/pub/v/{package}.svg` |

| Likes | `/pub/likes/{package}.svg` |

| Points | `/pub/points/{package}.svg` |

| Popularity | `/pub/popularity/{package}.svg` |

### Homebrew

| Badge | URL |

|-------|-----|

| Formula version | `/homebrew/v/{formula}.svg` |

| Cask version | `/homebrew/cask/{cask}.svg` |

| Installs (30d) | `/homebrew/installs/{formula}[/{days}].svg` |

| Formula downloads (monthly) | `/homebrew/dm/{formula}.svg` |

| Formula downloads (quarterly) | `/homebrew/dq/{formula}.svg` |

| Formula downloads (yearly) | `/homebrew/dy/{formula}.svg` |

| Cask downloads (monthly) | `/homebrew/cask-dm/{cask}.svg` |

| Cask downloads (quarterly) | `/homebrew/cask-dq/{cask}.svg` |

| Cask downloads (yearly) | `/homebrew/cask-dy/{cask}.svg` |

### Maven

| Badge | URL |

|-------|-----|

| Version | `/maven/v/{groupId}/{artifactId}.svg` |

### CocoaPods

| Badge | URL |

|-------|-----|

| Version | `/cocoapods/v/{pod}.svg` |

### Conda

| Badge | URL |

|-------|-----|

| Version | `/conda/v/{channel}/{package}.svg` |

| Downloads | `/conda/d/{channel}/{package}.svg` |

| Platform | `/conda/platform/{channel}/{package}.svg` |

### Chrome Web Store

| Badge | URL |

|-------|-----|

| Version | `/chrome/v/{extensionId}.svg` |

| Users | `/chrome/users/{extensionId}.svg` |

| Rating | `/chrome/rating/{extensionId}.svg` |

### Firefox Add-ons (AMO)

| Badge | URL |

|-------|-----|

| Version | `/amo/v/{slug}.svg` |

| Users | `/amo/users/{slug}.svg` |

| Rating | `/amo/rating/{slug}.svg` |

| Downloads | `/amo/d/{slug}.svg` |

### Codecov

| Badge | URL |

|-------|-----|

| Coverage | `/codecov/{service}/{owner}/{repo}[/{branch}].svg` |

Service: `github`, `gitlab`, `bitbucket`.

### Coveralls

| Badge | URL |

|-------|-----|

| Coverage | `/coveralls/{service}/{owner}/{repo}[/{branch}].svg` |

Service: `github`, `gitlab`, `bitbucket`.

### SonarQube

| Badge | URL |

|-------|-----|

| Quality gate | `/sonar/quality-gate/{component}.svg` |

| Bugs | `/sonar/bugs/{component}.svg` |

| Vulnerabilities | `/sonar/vulnerabilities/{component}.svg` |

| Code smells | `/sonar/code-smells/{component}.svg` |

| Coverage | `/sonar/coverage/{component}.svg` |

| Duplicated lines | `/sonar/duplicated-lines/{component}.svg` |

| Maintainability | `/sonar/maintainability/{component}.svg` |

| Reliability | `/sonar/reliability/{component}.svg` |

| Security | `/sonar/security/{component}.svg` |

Supports `?server=` for self-hosted instances.

### jsDelivr

| Badge | URL |

|-------|-----|

| Hits (monthly) | `/jsdelivr/hits/npm/{package}.svg` |

| Hits (yearly) | `/jsdelivr/dy/npm/{package}.svg` |

| GitHub hits | `/jsdelivr/hits/gh/{owner}/{repo}.svg` |

| Rank | `/jsdelivr/rank/npm/{package}.svg` |

### WakaTime

| Badge | URL |

|-------|-----|

| Coding time | `/wakatime/{username}.svg` |

### Tokscale

| Badge | URL |

|-------|-----|

| Tokens | `/tokscale/tokens/{username}.svg` |

| Cost | `/tokscale/cost/{username}.svg` |

| Rank | `/tokscale/rank/{username}.svg` |

| Active days | `/tokscale/active-days/{username}.svg` |

| Global stats | `/tokscale/stats.svg` |

### IndieDevs

| Badge | URL |

|-------|-----|

| User | `/indiedevs/{username}.svg` |

### Chocolatey

| Badge | URL |

|-------|-----|

| Version | `/chocolatey/v/{package}.svg` |

| Downloads | `/chocolatey/dt/{package}.svg` |

### Flathub

| Badge | URL |

|-------|-----|

| Version | `/flathub/v/{appId}.svg` |

| Downloads | `/flathub/downloads/{appId}.svg` |

### Snapcraft

| Badge | URL |

|-------|-----|

| Version | `/snapcraft/v/{snap}.svg` |

### F-Droid

| Badge | URL |

|-------|-----|

| Version | `/fdroid/v/{appId}.svg` |

### Discourse

| Badge | URL |

|-------|-----|

| Topics | `/discourse/topics/{server}.svg` |

| Posts | `/discourse/posts/{server}.svg` |

| Users | `/discourse/users/{server}.svg` |

| Likes | `/discourse/likes/{server}.svg` |

### Stack Exchange

| Badge | URL |

|-------|-----|

| Tag questions | `/stackexchange/tag/{tag}.svg` |

| Reputation | `/stackexchange/reputation/{userId}.svg` |

Supports `?site=` (default: `stackoverflow`).

### Modrinth

| Badge | URL |

|-------|-----|

| Downloads | `/modrinth/downloads/{slug}.svg` |

| Followers | `/modrinth/followers/{slug}.svg` |

| Version | `/modrinth/v/{slug}.svg` |

| Game versions | `/modrinth/game-versions/{slug}.svg` |

### Open VSX

| Badge | URL |

|-------|-----|

| Version | `/openvsx/v/{namespace}/{extension}.svg` |

| Downloads | `/openvsx/downloads/{namespace}/{extension}.svg` |

| Rating | `/openvsx/rating/{namespace}/{extension}.svg` |

### Liberapay

| Badge | URL |

|-------|-----|

| Receiving | `/liberapay/receiving/{username}.svg` |

| Patrons | `/liberapay/patrons/{username}.svg` |

| Goal | `/liberapay/goal/{username}.svg` |

### Matrix

| Badge | URL |

|-------|-----|

| Members | `/matrix/members/{roomAlias}.svg` |

Supports `?server=` (default: `matrix.org`).

### Weblate

| Badge | URL |

|-------|-----|

| Translation | `/weblate/translation/{server}/{project}/{component}.svg` |

| Languages | `/weblate/languages/{server}/{project}/{component}.svg` |

### Static & dynamic

| Badge | URL |

|-------|-----|

| Static | `/badge/{label}-{message}-{color}.svg` |

| Dynamic JSON | `/badge/dynamic/json.svg?url=...&query=...` |

| HTTPS endpoint | `/https/{hostname}/{path}.svg` |

| Memo (writable) | `/memo/{key}.svg` |

## Query parameters

### Appearance

| Param | Values | Default |

|-------|--------|---------|

| `variant` | `default`, `secondary`, `outline`, `ghost`, `destructive`, `branded` | `default` |

| `size` | `xs`, `sm`, `default`, `lg` | `sm` |

| `mode` | `dark`, `light` | `dark` |

| `theme` | `zinc`, `slate`, `blue`, `green`, `rose`, `orange`, `violet`, `purple`, `cyan`, `emerald` | — |

| `font` | `inter`, `geist`, `geist-mono` | `inter` |

### Colors

| Param | Description |

|-------|-------------|

| `color` | Override badge background color (hex without #) |

| `labelColor` | Override label-side background for split mode (hex without #) |

| `valueColor` | Override value text color (hex without #) |

| `labelTextColor` | Override label text color (hex without #) |

| `labelOpacity` | Label text opacity, 0–1 (default: 0.7) |

| `gradient` | Comma-separated hex colors, optional angle last (e.g. `ff6b6b,4ecdc4,135`) |

### Icons

| Param | Description |

|-------|-------------|

| `logo` | SimpleIcons slug (`react`), Lucide (`lu:Check`), React Icons (`ri:FaReact`), base64 SVG data URI, or `false` to hide |

| `logoColor` | Override icon color (hex without #) |

Three icon libraries with 40,000+ icons total, plus custom SVG upload.

- **SimpleIcons**: bare slug — `?logo=react`, `?logo=typescript`

- **Lucide**: `lu:` prefix — `?logo=lu:Check`, `?logo=lu:CircleCheck`, `?logo=lu:ArrowRight`

- **React Icons**: `ri:` prefix — `?logo=ri:FaReact`, `?logo=ri:MdHome`

### Layout

| Param | Description |

|-------|-------------|

| `label` | Override label text |

| `split` | `true` for two-tone split background |

| `statusDot` | `true`/`false` — colored dot before label (auto for CI) |

| `height` | Badge height in px |

| `fontSize` | Font size in px |

| `radius` | Border radius in px |

| `padX` | Horizontal padding in px |

| `iconSize` | Icon size in px |

| `gap` | Gap between icon and text in px |

| `labelGap` | Gap between label and value in px |

## Examples

```markdown

<!-- npm version badge -->


<!-- GitHub stars with secondary variant -->


<!-- CI status with outline variant -->


<!-- Custom static badge -->


<!-- Branded variant (uses provider brand color as background) -->


<!-- Split mode -->


<!-- Light mode -->


<!-- Custom icon with Lucide -->


<!-- Gradient background -->


<!-- Discord online count -->


<!-- PyPI version -->


<!-- Docker pulls -->


<!-- Bluesky followers -->


<!-- GitLab stars -->


```

## Key differences from shields.io

- Badges look like shadcn/ui Button components, not flat rectangles

- 6 variants (default, secondary, outline, ghost, destructive, branded)

- 16 color themes from shadcn palette

- Gradient backgrounds with custom angles

- 40,000+ icons from SimpleIcons + Lucide + React Icons

- Custom SVG icon upload via base64 data URI

- Split mode with two-tone backgrounds

- Status dots for CI badges

- Dark and light mode

- 45+ data providers (npm, GitHub, GitLab, PyPI, Docker, Bluesky, YouTube, and many more)

- Free, open source, MIT licensed

## Agent skill

Install the shieldcn agent skill to let AI coding agents add badges to projects:

```bash

npx skills add jal-co/shieldcn

```

Works with Claude Code, Cursor, Codex, Windsurf, and 40+ more agents via [skills.sh](https://skills.sh). The skill teaches agents all shieldcn providers, URL patterns, query parameters, and markdown best practices for badge rows.

Install globally to use across all projects:

```bash

npx skills add jal-co/shieldcn -g

```

Install to a specific agent:

```bash

npx skills add jal-co/shieldcn -a claude-code

```

## Links

- Homepage: https://shieldcn.dev

- Documentation: https://shieldcn.dev/docs

- Agent Skill: https://shieldcn.dev/docs/skill

- API Reference: https://shieldcn.dev/docs/api-reference

- Showcase: https://shieldcn.dev/showcase

- Badge Generator: https://shieldcn.dev/gen

- GitHub: https://github.com/jal-co/shieldcn