Markdown Badges: Shields.io Guide with Copy-Paste Examples
How to add status, version, license, and tech stack badges to your README
What Are Markdown Badges?
Badges are small status images you see at the top of many README files: build passing, latest version, license, supported language. They are not a special Markdown feature. A badge is a regular Markdown image whose URL points to a service that generates the picture on the fly. The most popular service is shields.io.
The basic syntax is the standard image syntax with a shields.io URL:
The URL has three parts separated by dashes: the label (left side), the message (right side), and the color. The alt text is what screen readers announce and what shows if the image fails to load, so make it meaningful.
Basic Badge Syntax
Every static shields.io badge follows the same pattern. Break it down:
https://img.shields.io/badge/LABEL-MESSAGE-COLOR| Part | Where it appears | Example |
|---|---|---|
| LABEL | Left side, dark grey | build |
| MESSAGE | Right side, colored | passing |
| COLOR | Background of the right side | brightgreen or 4c1 |
A complete example, with its rendered look:
Special characters in labels
Because the dash separates the parts, a few characters need escaping inside the label or message:
| You want | Write |
|---|---|
| A space | _ or %20 |
| A literal dash | -- |
| A literal underscore | __ |
Static Badges
Static badges show text you write yourself. Use them for anything that does not change often: project status, supported platforms, or a license. Change the last part of the URL to change the color. Named colors and hex codes (without the #) both work.
The named colors at a glance:
| Name | Preview | Typical use |
|---|---|---|
brightgreen | colorbrightgreen | Passing, active, success |
green | colorgreen | Good, stable |
yellow | coloryellow | Warning, in progress |
orange | colororange | Beta, caution |
red | colorred | Failing, deprecated |
blue | colorblue | Informational, platform |
lightgrey | colorlightgrey | Inactive, neutral |
For a custom color, use a six-digit hex code without the hash: https://img.shields.io/badge/brand-MDViewer-8A2BE2.
Dynamic Badges
Dynamic badges ask shields.io to look up live data, so the badge updates itself when your package version, star count, or CI result changes. Replace the uppercase placeholders with your own values.
npm version
GitHub stars
License
Build status (GitHub Actions)
Other common dynamic patterns follow the same shape: /github/v/release/USER/REPO for the latest release, /github/last-commit/USER/REPO for the last commit date, and /pypi/v/PACKAGE for a Python package. The previews above use sample values. Real badges show your project’s live data.
Badge Styles
Add ?style=NAME to the end of the URL to change the look. The default is flat. Available styles are flat, flat-square, plastic, for-the-badge, and social.
Pick one style and use it for every badge in the file. Mixed styles look messy. For multiple parameters, join them with &, for example ?style=flat-square&logo=python&logoColor=white.
Adding Logos
Shields.io can embed a brand logo on the left side of any badge using the logo parameter. Logos come from the Simple Icons set. Use logoColor to change the icon color. White works well on dark and colored backgrounds.
Common logo names to use with ?logo=:
| Technology | Logo name |
|---|---|
| Python | python |
| JavaScript | javascript |
| TypeScript | typescript |
| React | react |
| Node.js | nodedotjs |
| Docker | docker |
| AWS | amazonaws |
| GitHub | github |
Logo availability depends on the current Simple Icons release. If a logo does not show, search for the exact name on simpleicons.org. Some brand logos have been removed over time.
Tech Stack Badges
A tech stack row tells visitors what your project is built with. Here is a copy-paste collection for popular technologies. Each badge uses a brand color with a matching logo. Keep only the ones that apply to your project.
Put them on consecutive lines or on a single line separated by spaces. Both render as a row. For a different technology, swap the name, the hex color (look up the brand color on simpleicons.org), and the logo value.
The previews on this page are simplified drawings that show colors and layout. Real shields.io badges also include the logo and are rendered by shields.io.
Best Practices
- Group badges logically. Put status badges (build, coverage) together, then version and license, then tech stack and social links on separate lines.
- Do not overdo it. Five to ten badges in a row is plenty. A wall of badges hides the information people actually need.
- Use one consistent style. Pick
flat,flat-square, orfor-the-badgeand apply it to every badge. - Keep them up to date. Prefer dynamic badges for versions and build status. A stale static badge that says “passing” is worse than no badge.
- Write useful alt text.
is better thanfor accessibility and for when images fail to load. - Link badges where it helps. Wrap a build badge in a link to your CI page and a license badge in a link to your LICENSE file.
FAQ
How do I add a badge to my GitHub README?
Add an image line to your README.md with the shields.io URL, for example . GitHub renders it as a badge when the README is displayed. To make it clickable, wrap it in a link: [](link-url).
How do I change the color of a shields.io badge?
For static badges, change the last part of the URL: .../status-active-brightgreen becomes .../status-active-red. You can use a named color (brightgreen, green, yellow, orange, red, blue, lightgrey) or a hex code without the #. For dynamic badges, add ?color=blue to the end of the URL. Use ?labelColor=black to change the left side.
Can I create custom badges with my own text?
Yes. Use the static format https://img.shields.io/badge/LABEL-MESSAGE-COLOR and fill in your own text. Use an underscore or %20 for a space, -- for a literal dash, and __ for a literal underscore. No account or API key is needed.
Preview Your Markdown with MDViewer
MDViewer is a native macOS app for reading and previewing Markdown files. Double-click any .md file in Finder and see it rendered instantly — headings, tables, code blocks, images, and more. Lite is free; Pro adds editing, Git history, and PDF export.
Requires macOS 13.0 or later. Intel and Apple Silicon.
Social Badges
Social badges link to your profiles. To make any badge clickable, wrap the image syntax in a link. The format is
[](link-url).Here is a ready-made set for the most common profiles. Replace the placeholders with your own handles and URLs.
Shields.io also has a live
socialstyle for follower counts on some platforms. For example,https://img.shields.io/github/followers/USER?style=socialshows your GitHub follower count.