GitHub README Badges — The Complete Guide to Shields.io

Badges are the small status indicators at the top of a README that show build status, version, licence, and test coverage at a glance. They signal that a project is maintained, tested, and professional.

Essential badges for every project

Build status

Shows whether your CI pipeline is passing. This is the single most important badge — a failing build tells visitors the project might be broken.

npm version

For published packages, show the current version on npm:

Licence

Let people know immediately whether they can use your code:

Test coverage

If you use Codecov, Coveralls, or a similar service:

Useful optional badges

Downloads

TypeScript

Signal that your package includes type definitions:

Bundle size

Important for frontend libraries — developers care about what they ship:

Last commit

Shows the project is actively maintained:

Custom badges with Shields.io

Shields.io lets you create any badge with a simple URL pattern:

Colours can be hex codes (without #) or named colours: green, blue, red, orange, yellow, brightgreen.

Examples:

• https://img.shields.io/badge/Node-18+-green
• https://img.shields.io/badge/PRs-Welcome-brightgreen
• https://img.shields.io/badge/Status-Beta-orange

Badge placement rules

• Put them at the top — Right after the project title, before the description.
• Keep it under 6 — More than 6 badges looks cluttered. Pick the most relevant ones.
• Order by importance — Build status first, then version, then licence, then optional badges.
• Don't badge what doesn't change — A “Made with JavaScript” badge adds no information.

Common mistakes

• Broken badges — Test every badge URL. A broken badge image is worse than no badge.
• Vanity badges — “Made with ❤️” tells visitors nothing. Every badge should convey useful information.
• Stale badges — If your CI badge shows “failing” for months, remove it or fix the pipeline.