Web & APIs · 3 min read
README Badges: What They Are and Which to Add
The small coloured labels at the top of many GitHub READMEs — build passing, version 2.4.1, license MIT — are badges. Used well, they answer a visitor's first questions at a glance.
Try it yourself with the related tool.
Create a README badge →Advertisement
How badges work
A badge is just an image, usually an SVG generated on the fly by a service such as shields.io. The URL encodes the label, message, and colour, for example https://img.shields.io/badge/license-MIT-blue. Dynamic badges query a source like npm or GitHub Actions so the value updates itself.
In Markdown, a badge is an image wrapped in a link: [](link-url), so clicking it leads to the CI run, the package page, or the license file.
Badges worth adding
The useful ones answer real questions: does it build (CI status), what is the latest version (npm, PyPI, crates.io), can I use it (license), and is it maintained (last commit or release). Coverage and download counts are useful for libraries.
Keep it short
Three to six badges is plenty. A wall of twenty icons pushes the actual description below the fold. Always set meaningful alt text — screen-reader users otherwise hear only "image" over and over.