How to Add GitHub Stats Cards to Your README (2026 Guide)
Step-by-step guide to adding GitHub stats cards, language cards, streak stats, and WakaTime cards to your GitHub profile README using github-readme-stats.
Dynamic stats cards are the difference between a static README and one that tells a living story. When recruiters or collaborators visit your profile, a well-placed stats card answers the question they're really asking: does this developer actually ship code?
This guide covers every major card type from the anuraghazra/github-readme-stats ecosystem — the most popular GitHub profile stats tool with over 70,000 stars — plus streak stats, WakaTime cards, and how to arrange them so your README doesn't look like a dashboard exploded.
The GitHub Stats Card
The core stats card shows your total stars earned, total commits, pull requests, issues, and contribution score. Adding it takes one line of markdown:
Replace YOUR_USERNAME with your actual GitHub username. That's it. No tokens, no configuration files, no GitHub Actions workflow to set up.
Key parameters to know:
| Parameter | What it does | Example |
|-----------|-------------|---------|
| show_icons=true | Adds icons next to each stat | &show_icons=true |
| theme | Sets the color theme | &theme=tokyonight |
| hide | Hides specific stats | &hide=contribs,prs |
| count_private=true | Counts private repo contributions | &count_private=true |
| include_all_commits=true | Shows commits from all years, not just the current year | &include_all_commits=true |
The count_private=true parameter matters more than most people realize. If you do meaningful work in private repos — which most professional developers do — your stats will look deflated without it. Enable it, and your contribution graph reflects reality.
Picking a Theme
The stats card ships with 30+ themes. The most commonly used:
default— light mode, blue accentsdark— dark background, white textradical— pink/purple gradient, high contrasttokyonight— dark navy with pastel accents, very popular in 2025-2026dracula— dark with purple highlightsgruvbox— warm amber and green, readable at any sizetransparent— no background; blends with GitHub's own page background
For most profiles, transparent or tokyonight work well across both GitHub's light and dark modes. Avoid themes with light backgrounds on dark mode profiles — they create an awkward white box effect.
The Top Languages Card
The language card shows which programming languages appear most in your public repositories, weighted by byte count:
Layouts:
layout=default— bar chart for each languagelayout=compact— smaller card, one row per languagelayout=donut— pie chart (visually interesting, but can be hard to read)layout=pie— similar to donutlayout=donut-vertical— vertical donut layout
The compact layout is the most readable when placed side-by-side with the stats card.
An honest caveat: the language card counts bytes of code, not time spent or proficiency. If you forked a large JavaScript project once, it'll dominate your chart. You can exclude repos that skew your results:
You can also hide specific languages (useful for excluding HTML/CSS from a portfolio that's mostly JavaScript):
GitHub Streak Stats
Streak stats show your current contribution streak, longest streak ever, and total contributions. This comes from a separate project — DenverCoder1/github-readme-streak-stats:
[](https://git.io/streak-stats)
Note the URL is streak-stats.demolab.com, not the github-readme-stats domain. The streak card has its own theming system with matching themes (tokyonight, dark, radical, etc.).
Why streak stats matter for your profile: Consistency is a proxy for reliability. A long streak tells a visitor you code regularly, not just in bursts around hackathons. Even a modest 30-day streak signals active engagement with your craft.
One practical note: GitHub only counts contributions on days you push commits, open PRs, review code, or create issues in the default branch. Contributions to non-default branches don't count unless they get merged.
WakaTime Coding Activity Card
If you use WakaTime to track your coding time, you can display it as a card showing time per language over the past week:
Note this uses your WakaTime username, not your GitHub username. You'll need to:
- Sign up for WakaTime (free plan available)
- Install the WakaTime plugin for your editor (VS Code, JetBrains, Vim, etc.)
- Find your WakaTime username in your profile settings
- Make your WakaTime profile public (required for the card to work)
The WakaTime card is the most compelling card for demonstrating active, recent coding activity. Real hours logged per week is harder to fake than GitHub contribution counts.
Arranging Multiple Cards
Most READMEs that include stats cards go wrong in the same way: they stack cards vertically, turning the README into an endless scroll. The better approach is to place them side by side using a simple HTML table:
<div align="center">
<img src="https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&show_icons=true&theme=tokyonight&count_private=true" height="150" />
<img src="https://github-readme-stats.vercel.app/api/top-langs/?username=YOUR_USERNAME&layout=compact&theme=tokyonight" height="150" />
</div>
The height="150" attribute forces both cards to the same height, creating a clean two-column layout. You can add the streak card below:
<div align="center">
<img src="https://streak-stats.demolab.com?user=YOUR_USERNAME&theme=tokyonight" height="150" />
</div>
Don't use all four cards. Pick two or three that tell the most relevant story for where you are in your career:
- Students and juniors: Stats card + Languages card. Show you're actively learning.
- Mid-level engineers: Stats card + Streak card. Show consistency.
- Senior engineers and leads: WakaTime card + Stats card. Time invested speaks for itself.
Self-Hosting for Reliability
The public github-readme-stats instances have rate limits. If your profile gets significant traffic, cards may occasionally fail to load and display a broken image. The project is open source — you can deploy your own instance on Vercel in about 5 minutes:
- Fork anuraghazra/github-readme-stats
- Deploy to Vercel (one-click, no configuration needed)
- Set the
PAT_1environment variable to a GitHub personal access token - Replace the domain in your card URLs with your own Vercel URL
Self-hosting eliminates rate limit issues and gives you control over the instance. For anyone whose profile is a professional showcase, it's worth the 5-minute setup.
Troubleshooting Common Issues
Card shows "Maximum retries exceeded": The API is rate-limited. Wait a few minutes or consider self-hosting.
Language percentages don't look right: Check exclude_repo to remove forked or unused repos. Add &hide=html,css to exclude markup languages if you're primarily a backend developer.
Stats look low for a senior developer: Add &count_private=true and &include_all_commits=true. Many experienced engineers do most of their work in private repositories.
Cards don't match across light/dark mode: Use the transparent theme. GitHub renders the card's background as transparent, matching whatever theme the visitor has set.
Putting It Together
A complete stats section might look like this:
<div align="center">
<img src="https://github-readme-stats.vercel.app/api?username=johndoe&show_icons=true&theme=tokyonight&count_private=true&include_all_commits=true" height="150" />
<img src="https://github-readme-stats.vercel.app/api/top-langs/?username=johndoe&layout=compact&theme=tokyonight&hide=html,css" height="150" />
</div>
<div align="center">
<img src="https://streak-stats.demolab.com?user=johndoe&theme=tokyonight" height="150" />
</div>
Readable, consistent theming, and no card that doesn't earn its space. Your README should answer "can this person code?" in about 10 seconds. Stats cards, done right, do exactly that.
Generate Your Full README
Stats cards are one piece. An effective GitHub profile README also needs a clear headline, project showcases, and a call to action. Use our AI GitHub Profile README Generator to build the complete picture — it reads your actual GitHub data and writes a README tailored to your profile, skills, and the impression you want to make.