Shields.io README Badges

Shields.io badges for your README at a glance

Shields.io is the open-source badge service launched in 2014 by Olivier Lacan and Cees-Jan Kiewiet. It serves small SVG images that summarise project metadata — build status, latest version, license, coverage, download counts — and became the de facto standard for the badge strip you see at the top of almost every popular GitHub README. The badge is just an image URL, so it works in Markdown, AsciiDoc, RST, HTML, JIRA wiki and anywhere else where you can embed an image.

The simplest URL pattern is https://img.shields.io/badge/Label-Message-color. Dynamic badges replace that path with a route that fetches live data, for example /npm/v/express for the current npm version of express, or /github/stars/torvalds/linux for the star count. Shields caches each badge for about five minutes, which keeps the service fast and your upstream APIs out of trouble.

Colours, styles and logos

Named colours include brightgreen, green, yellow, orange, red, blue, lightgrey plus semantic aliases success, important, critical and informational; any hex value also works (#ff69b4). Style query params change the typography: ?style=flat (default), flat-square, plastic, for-the-badge (uppercase and bigger), social. Adding ?logo=github&logoColor=white embeds a brand icon — Shields pulls from SimpleIcons, which covers over a thousand brand marks.

Useful dynamic endpoints

• /npm/v/<package> — latest npm version
• /github/actions/workflow/status/<owner>/<repo>/<workflow>.yml — GitHub Actions status
• /codecov/c/github/<owner>/<repo> — Codecov coverage percentage
• /github/license/<owner>/<repo> — license auto-detected from the repo
• /github/last-commit/<owner>/<repo> — freshness signal
• /endpoint?url=... — points at your own JSON, perfect for fully custom badges

Common badge anti-patterns

Badges signal maturity and let visitors click straight through to the dashboard behind each metric, but they only work when curated. A few traps to avoid: badge inflation — stacking ten or more rows of badges drowns out the actual project description, pick four to six essentials; broken badges — leaving a Travis CI badge after migrating to GitHub Actions, or a Codecov badge after the upload step was removed; green-only badges — a metric that is always passing communicates nothing, drop it; vanity tags — "Made with love" or stack-flair badges add visual noise without informing the reader.

FAQ

Do I need to host anything? No. Shields.io hosts every SVG. You just embed the URL.

What happens if Shields gets rate-limited by the upstream API? The badge falls back to a generic "invalid" state and Shields caches the result for a few minutes before retrying. The README still renders — only that badge looks broken until upstream recovers.

Can I customise the badge entirely? Yes. Host a JSON file that exposes { "schemaVersion": 1, "label": "...", "message": "...", "color": "..." } and point a Shields /endpoint?url=... badge at it. You control label, value, colour, logo and style.

Are there alternatives to Shields? Badgen.net mirrors most endpoints with extra customisation, and forthebadge.com ships a tongue-in-cheek style set. Shields remains the broadest and most reliable.