GitHub README Badges: The Complete Shields.io Guide

Badges are the small coloured labels you see on almost every polished README: a tech stack, social links, build status, version numbers. Nearly all of them come from shields.io, a free service that turns a URL into a badge image. Once you understand the URL format, you can make any badge you want.

Anatomy of a badge URL

A static badge looks like this:

https://img.shields.io/badge/<LABEL>-<COLOR>?style=<STYLE>&logo=<LOGO>&logoColor=<COLOR>

For example:

https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white

Label: the text on the badge.
Color: a hex colour without the # (007ACC) or a named colour (blue, brightgreen).
logo: an icon slug from Simple Icons, e.g. react, nextdotjs, nodedotjs, postgresql.
logoColor: the icon colour, usually white.

You can also use a two-part badge with a label and a message: /badge/<LABEL>-<MESSAGE>-<COLOR>, e.g. /badge/status-active-brightgreen.

Escaping special characters

Dashes and underscores separate the parts of the URL, so they need escaping inside text:

You want	Write
A dash `-`	`--` (e.g. `Scikit--learn`)
An underscore `_`	`__`
A space	`_` or `%20`
Characters like `#`, `+`, `/`	URL-encode them: `C%23` for C#, `C%2B%2B` for C++

Badge styles

Add ?style= to change the shape. for-the-badge is the most popular choice for tech stacks:

`flat`
`flat-square`
`plastic`
`for-the-badge`
`social`

Making badges clickable

Wrap the image in a link. In Markdown:

[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://linkedin.com/in/your-name)

Or in HTML, which you'll need if the badges sit inside a centred block:

<a href="https://linkedin.com/in/your-name">
  <img src="https://img.shields.io/badge/LinkedIn-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white" alt="LinkedIn" />
</a>

Spacing and centring badges on GitHub

GitHub removes CSS from READMEs, so you can't add margins with style="…". Badges on separate lines get a small gap from the whitespace between them, but rows can end up touching. GitHub does keep the hspace and vspace image attributes, which add space around each badge:

<p align="center">
  <img src="https://img.shields.io/badge/PHP-777BB4?style=for-the-badge&logo=php&logoColor=white" alt="PHP" hspace="3" vspace="3" />
  <img src="https://img.shields.io/badge/Laravel-FF2D20?style=for-the-badge&logo=laravel&logoColor=white" alt="Laravel" hspace="3" vspace="3" />
</p>

align="center" on a <p> or <div> centres everything inside it.

Dynamic badges

Shields.io can also show live data. A few useful ones for repository READMEs:

https://img.shields.io/github/stars/<user>/<repo>?style=social
https://img.shields.io/github/license/<user>/<repo>
https://img.shields.io/github/last-commit/<user>/<repo>
https://img.shields.io/npm/v/<package>

Browse the full catalogue at shields.io/badges.

Alternative: icon rows

If you prefer icons without text, skillicons.dev renders a neat row from one URL:

https://skillicons.dev/icons?i=ts,react,nextjs,nodejs,docker&perline=10

Tips

Use brand colours: they're recognisable at a glance. Simple Icons lists the official hex for every logo.
Keep it honest and focused. Ten technologies you actually use beat forty you've touched once.
Always set alt text. It's what screen readers announce, and it shows if an image fails to load.
Group badges by category (languages, frameworks, tools) when you have many.

💡 MakeReadme has 75+ tech badges with the right colours and logos built in, grouped by category, with spacing handled for you. Try it →

Next: add live GitHub stats to your README.