GitHub Stat Badges: The Complete Guide to Embedding Live Stats
Everything about GitArena's embeddable GitHub badges — the stats card, compact pill, and contribution graph, with every parameter, layout recipes for light and dark READMEs, and fixes for badges that won't render.
A GitHub stat badge is a small image that reports something true about you — how many commits you’ve made, how long your streak is, where you rank — and refreshes itself without you touching it. Drop one line of Markdown into a README and it keeps telling the story long after you wrote it.
This guide covers the three badges GitArena serves: what each one shows, every parameter you can tune, where they work besides your profile README, and what to do when one won’t render. If you just want the snippet for your account, the Badges page generates it with a live preview — this post is the reference behind it.
How the badges actually work
Each badge is an SVG image generated on request by a GitArena endpoint. The URL follows one shape:
https://gitarena.dev/api/badge/YOUR_USERNAME[/style]?optionsWhen GitHub renders your README, it fetches that URL, GitArena looks up your current stats, draws the SVG, and sends it back. A few consequences worth knowing:
- Nothing to install, no token to manage. It’s an image tag. There’s no GitHub Action writing to your repo, no personal access token to rotate, and nothing to expire.
- Your avatar is baked in. The stats and graph badges embed your GitHub avatar directly in the SVG as data, so it survives GitHub’s image proxy instead of showing up as an empty circle.
- Responses are cached for an hour. Badges are served with a one-hour cache, and your underlying stats are re-pulled from GitHub daily. A badge is current, not real-time — see freshness below.
- You need a GitArena profile first. Sign in with GitHub once so there are stats to render. Until then the endpoint returns a polite “user not found” card rather than a broken image.
1. The stats card
The flagship badge: a 540×210 card with your avatar, username, and current rank in the header, then three numbers across the bottom — commits, day streak, and your GitArena score.
[](https://gitarena.dev)Or as HTML, if you want to pin the dimensions and control alignment:
<a href="https://gitarena.dev">
<img src="https://gitarena.dev/api/badge/YOUR_USERNAME?timeframe=total&theme=light&color=purple"
alt="GitArena Stats" width="540" height="210" />
</a>This is the badge to use when you have room for one substantial visual — near the top of a profile README, under your headline. Here it is in both themes:
And the same card across the three timeframes — note that the label under the commit count changes with it, so the badge always says which window it’s reporting:
2. The compact pill
A shields.io-style pill, 28 pixels tall, showing your rank and score as #12 · 1,840. It sits inline next to your other badges — build status, license, language — without breaking the row.
[](https://gitarena.dev)The pill’s width is computed from the text it contains, so if you embed it as HTML, set height only and leave width alone — pinning both will squash it:
<a href="https://gitarena.dev">
<img src="https://gitarena.dev/api/badge/YOUR_USERNAME/pill?timeframe=total&theme=light&color=purple"
alt="GitArena" height="28" />
</a>One nice property: the pill’s value block uses your accent color at full strength, so it stays readable on light and dark README backgrounds alike. Only the label block changes with the theme — which is the pair above, light then dark.
3. The contribution graph
A 540×175 line chart of your last 30 days of commits. Where the stats card proves volume, the graph proves rhythm — it makes a consistent month look consistent at a glance.
[](https://gitarena.dev)The window is fixed at 30 days, so the graph takes theme and color but no timeframe.
Every parameter, in one place
| Parameter | Values | Default | Applies to |
|---|---|---|---|
timeframe | total, year, month | total | Stats card, pill |
theme | light, dark | light | All three |
color | purple, blue, green, orange, pink | purple | All three |
All five accent colors, on the pill:
Anything unrecognized falls back to the default instead of erroring, so a typo in color=purpel gives you a purple badge, not a broken one. Handy, but worth knowing when a color you asked for doesn’t appear — check the spelling first.
Choosing a timeframe
timeframe changes the numbers and the label under them, and it changes your rank too — rank is recomputed against everyone else on the same timeframe. That makes the three options genuinely different claims:
total— lifetime commits and your longest-ever streak. Rewards years of work; best for an established profile.year— the last 12 months. The fairest read on what you’re doing now, and the one most people should pick.month— the last 30 days. Volatile by design; good if you’re in a sprint and want the badge to show it.
What the score means
The GitArena score isn’t a commit count with extra steps. For the timeframe you pick, it’s:
score = (commits × 0.6) + (streak × 1.4)Streak days are weighted more than raw commits on purpose. Ten commits dumped in one afternoon move the number less than ten days of showing up — the score is meant to reward consistency, which is the harder and more honest signal.
Layout recipes
Auto-switching light and dark
GitHub renders READMEs in whichever theme the visitor uses. You can serve the matching badge with a <picture> element and a prefers-color-scheme media query:
<picture>
<source media="(prefers-color-scheme: dark)"
srcset="https://gitarena.dev/api/badge/YOUR_USERNAME?theme=dark&color=purple" />
<img src="https://gitarena.dev/api/badge/YOUR_USERNAME?theme=light&color=purple"
alt="GitArena Stats" width="540" height="210" />
</picture>Worth the four extra lines: a light badge on a dark profile is the single most common way these end up looking sloppy. The two the snippet picks between:
Centering and stacking
Markdown has no alignment, but GitHub allows a little HTML. To center the stats card and graph in a column:
<p align="center">
<img src="https://gitarena.dev/api/badge/YOUR_USERNAME?timeframe=year&theme=dark&color=blue" width="540" />
<br />
<img src="https://gitarena.dev/api/badge/YOUR_USERNAME/graph?theme=dark&color=blue" width="540" />
</p>Use the same color for both. Two badges in different accent colors read as two unrelated widgets rather than one considered block.
A row of pills
The pill is built to share a line. Put it at the end of your badge row so the stack reads left to right from project facts to personal ones:
[](https://gitarena.dev)In Markdown, images on consecutive lines with no blank line between them render on the same row.
Freshness: why the number isn’t instant
Two layers of caching sit between your last commit and the number on your badge:
- Your stats refresh daily. GitArena re-pulls contribution data for every tracked user once a day, at midnight UTC. You can also refresh your own stats on demand from your profile page.
- The image is cached for an hour. Each badge response carries a one-hour cache lifetime, and GitHub adds its own image proxy on top, which can hold a copy longer still.
So a commit you push this minute shows up on your badge within a day, not within seconds. That’s the right trade: badges that hammer an API on every page view get rate-limited into broken images, and a stat card that’s a few hours stale communicates exactly as well as one that’s current.
Troubleshooting
- “User not found” card. The username doesn’t match a GitArena profile. Check the spelling and the capitalization — the lookup is exact — and make sure you’ve signed in with GitHub at least once so your stats exist.
- Broken image icon. Almost always a malformed URL. Paste the badge URL straight into your browser: if it renders there, the problem is in your Markdown, usually an unescaped character or a missing closing parenthesis.
- Numbers look stale. Expected within a day — see freshness. If it’s been longer, refresh your stats from your profile, then hard-reload the README.
- The pill looks stretched. You set
widthon it. Setheight="28"and let the width follow the content. - Rank changed without you doing anything. Rank is relative. Other people commit too — and it’s computed per timeframe, so switching
timeframewill move it.
Beyond the profile README
Nothing about these badges is GitHub-specific — they’re plain SVG images at a public URL, so they work anywhere images do:
- Repo READMEs, not just your profile — a maintainer badge in your own projects.
- GitLab, Codeberg, and Bitbucket READMEs, which render the same Markdown.
- Dev.to, Hashnode, and personal sites — anywhere you keep an author bio.
- Gists and issue comments, where a pill makes a compact signature.
Putting it together
A good badge setup is three decisions, not thirty: pick the badge that fits the space (card for a hero slot, pill for a row, graph to show momentum), pick a timeframe that’s an honest read on your current work — year for most people — and use one accent color everywhere so the profile looks designed rather than assembled.
Then leave it alone. That’s the entire point: the badge keeps itself current while you get on with committing. For more on the README around it, see how to make your GitHub profile README stand out.
Generate your badge — pick a style, tune the options against a live preview, and copy the snippet.
Add live GitHub stats to your README
Generate an embeddable GitArena badge in seconds — customize the timeframe, theme, and color.
Generate your badge