Davide

Posted on May 9

GitHub Contribution Card: Dynamic SVG Stats Card for Your GitHub Profile README

#typescript #opensource #github #webdev

Ever wanted to show off not just how many commits you've made, but which repositories you actually contributed to — with stars, ranks, and themes? That's exactly what GitHub Contribution Card does.

🎬 Demo

🚀 Quick Start

Just paste this into your GitHub profile README or any Markdown file:

![My GitHub Contribution Stats](https://github-contribution-card.vercel.app/api?username=YOUR_USERNAME)

That's it. No setup, no tokens needed on your end.

✨ What It Shows

Each card displays your top repositories ranked by stars or contributions, assigning a rank to each one:

Star Ranks: S+ (10,000+) · S (1,000+) · A+ (500+) · A (100+) · B+ (50+) · B (1+)
Contributor Ranks: S+ (90+) · S (80+) · A+ (70+) · A (60+) · B+ (50+) · B (1+)

🎨 Themes

Use &theme=THEME_NAME to pick one of the 40+ built-in themes:

![Stats](https://github-contribution-card.vercel.app/api?username=YOUR_USERNAME&theme=tokyonight)

Some popular ones:

Theme	Style
`dracula`	Dark purple + pink
`tokyonight`	Deep blue night
`catppuccin_mocha`	Warm mocha tones
`github_dark`	Native GitHub dark
`one_dark_pro`	One Dark Pro feel
`ambient_gradient`	Gradient glow

You can also fully customize colors with &title_color=, &text_color=, &icon_color=, &bg_color=, and &border_color= (hex values, no #).

🌍 Locales

The card title can be translated into 20+ languages with &locale=CODE:

![Stats](https://github-contribution-card.vercel.app/api?username=YOUR_USERNAME&locale=it)

Supported languages include English, Italian, French, Spanish, German, Japanese, Portuguese, Korean, Arabic, Chinese, and more.

⚙️ API Parameters

Parameter	Type	Default	Description
`username`	string	—	(required) GitHub username
`theme`	string	`default`	Theme name
`limit`	number	`-1`	Max repos to show
`order_by`	string	`stars`	Sort by `stars` or `contributions`
`hide`	string	`""`	Comma-separated ranks to hide
`locale`	string	`en`	Language code
`combine_all_yearly_contributions`	boolean	`false`	Include all years
`hide_contributor_rank`	boolean	`true`	Hide contributor rank column
`hide_title`	boolean	`false`	Hide card title
`hide_border`	boolean	`false`	Hide card border

🐳 GitHub Action — For Power Users

The Vercel API can time out for profiles with 15+ years of contributions and 300+ repositories. The Docker-based GitHub Action solves this: no timeout, built-in rate limiting, SVG output committed directly to your repo.

name: Update Contribution Card
on:
  schedule:
    - cron: '0 0 * * *' # Daily at midnight
  workflow_dispatch:

jobs:
  update-stats:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Generate Contribution Card SVG
        uses: FrancoStino/github-contribution-card/action@main
        env:
          GITHUB_PERSONAL_ACCESS_TOKEN: ${{ secrets.GITHUB_PERSONAL_ACCESS_TOKEN }}
        with:
          username: YOUR_USERNAME
          output-file: github-contribution-card.svg
          combine-all-yearly-contributions: 'true'
          theme: default
          rate-limit-delay-ms: '100'

      - uses: actions4git/add-commit-push@v1
        continue-on-error: true

🛡️ Self-Hosting on Vercel

If you want your own instance:

Fork the repository
Import it in Vercel
Set GITHUB_PERSONAL_ACCESS_TOKEN in Settings → Environment Variables
Deploy — your API is live at https://<project>.vercel.app/api

For local development:

yarn install
cp .env.example .env
yarn build:prod
yarn start
# Server starts at http://localhost:9999

🤝 Contributing

Contributions are welcome! Open an issue or submit a pull request on GitHub.

⭐ If you find it useful, drop a star on the repo — it helps more developers discover it!

DEV Community