How to Add a GitHub Contribution Grid to Your Profile README

GitHub's contribution grid (also called the contribution calendar or activity heatmap) shows 52 weeks of daily contribution data as a grid of colored squares. Squares darken as contribution counts increase for that day. It is the most-recognized GitHub visualization and immediately communicates both activity level and consistency.

Embedding this in your README makes it visible above the fold rather than requiring visitors to scroll down your profile page. For developers with impressive contribution records — particularly long streaks or high-density periods of activity — this placement can significantly strengthen the first impression your profile makes.

Option 1: Activity graph (31-day view, no setup):

[![Contribution Grid](https://github-readme-activity-graph.vercel.app/graph?username=YOUR_USERNAME&theme=tokyo-night&area=true&hide_border=true&color=58A6FF&line=58A6FF&point=58A6FF)](https://github.com/YOUR_USERNAME)

Option 2: Full-year calendar via GitHub Metrics (requires Actions setup):

In your .github/workflows/metrics.yml, add:

plugin_calendar: yes
plugin_calendar_limit: 1

Then reference the generated metrics.svg in your README.

Option 3: Streak stats (shows longest streak + current streak):

[![Streak](https://streak-stats.demolab.com?user=YOUR_USERNAME&theme=tokyonight&hide_border=true)](https://git.io/streak-stats)

The streak stats card is the lightest option and communicates the most important derived metric from the contribution grid — whether you code consistently.

For the activity graph (Option 1), customize the colors to match your profile palette:

• color: Line and dot color (hex without #)
• line: Line color (overrides color for the line specifically)
• point: Data point dot color
• bg_color: Background color
• theme: Use a preset theme instead of individual colors
• area=true: Fill the area under the line for a more dramatic effect
• hide_border=true: Remove card border for a cleaner embedded look

For consistency with other widgets in your profile, use the same theme across all your widgets. If your profile uses tokyonight for stats and streak cards, use theme=tokyo-night for the activity graph (note the hyphen difference between the two services).

If the activity graph appears with a very flat line (few tall bars), this reflects your actual public contribution history. Large gaps in the graph correspond to days with no public commits, merged PRs, or other counted activities. Enable private contributions in your GitHub profile settings to make private repo activity visible.

If the image renders but shows no data at all, verify your GitHub username is correct in the URL and that you have made at least some public contributions in the past 31 days. Brand-new accounts may show an empty graph initially.

For the GitHub Metrics full-year calendar option, ensure the plugin_calendar: yes parameter is in your workflow and that the METRICS_TOKEN secret has the read:user scope. The calendar plugin reads your contribution data and renders it as a labeled grid within the metrics SVG.