Circle-pack badges
for any repo
Beautiful contributor graphs as SVG. Customize layout, colors, and borders — then drop one line of markdown into your README.
Add a repository to start
Repository
Private repos require the GitHub App installed on the owner account with access to that repository. No tokens in the badge URL.
Customize
Query parameters
Append to your badge URL. Omitted params use defaults. Colors are hex without #.
| Parameter | Type | Default | Description |
|---|---|---|---|
size | number | 1000 | Square canvas edge length in pixels (used when width/height are omitted) |
width | number | 1000 | Canvas width in pixels — overrides size for width only |
height | number | 1000 | Canvas height in pixels — overrides size for height only |
limit | number | 100 | How many top contributors to include (by commit count) |
bg | color | 0a0a0a | Background color as 6- or 8-digit hex without # |
padding | number | 2 | Space between circles in the pack layout |
rmin | number | 8 | Smallest circle radius (least active contributor) |
rmax | number | 300 | Largest circle radius (most active contributor) |
power | number | 0.9 | Curve for mapping commits to size — lower flattens, higher exaggerates top contributors |
borders | select | large | Which circles get a stroke: only large, every circle, or none |
border | color | 88888844 | Border stroke color as hex without # (8 digits = with alpha) |
border-width | number | 0.5 | Border stroke width in SVG units |
exclude | text | — | Comma-separated GitHub logins to omit (bots, dependabot, etc.) |
transparent | boolean | false | Same as bg=transparent — no background rectangle |
border-min | number | 25 | With borders=large, only circles above this radius get a border |
avatar-bg | color | 000000 | Fill behind avatar images (visible if the photo has transparency) |
margin | number | 0 | Inset around the circle pack inside the canvas |
bg-radius | number | 0 | Corner radius of the background rectangle (0 = square) |
cache | number | 86400 | CDN Cache-Control max-age in seconds (1h-7d). Controls how long GitHub/README caches the image URL |
sizenumberSquare canvas edge length in pixels (used when width/height are omitted)
1000widthnumberCanvas width in pixels — overrides size for width only
1000heightnumberCanvas height in pixels — overrides size for height only
1000limitnumberHow many top contributors to include (by commit count)
100bgcolorBackground color as 6- or 8-digit hex without #
0a0a0apaddingnumberSpace between circles in the pack layout
2rminnumberSmallest circle radius (least active contributor)
8rmaxnumberLargest circle radius (most active contributor)
300powernumberCurve for mapping commits to size — lower flattens, higher exaggerates top contributors
0.9bordersselectWhich circles get a stroke: only large, every circle, or none
largebordercolorBorder stroke color as hex without # (8 digits = with alpha)
88888844border-widthnumberBorder stroke width in SVG units
0.5excludetextComma-separated GitHub logins to omit (bots, dependabot, etc.)
—transparentbooleanSame as bg=transparent — no background rectangle
falseborder-minnumberWith borders=large, only circles above this radius get a border
25avatar-bgcolorFill behind avatar images (visible if the photo has transparency)
000000marginnumberInset around the circle pack inside the canvas
0bg-radiusnumberCorner radius of the background rectangle (0 = square)
0cachenumberCDN Cache-Control max-age in seconds (1h-7d). Controls how long GitHub/README caches the image URL
86400Before you embed
README cache
GitHub caches the image URL. Default cache is 24h (cache=86400). Change the URL or wait for expiry to see updates.
Contributor refresh
Data from GitHub updates about every 6 hours. New commits may lag even if you hard-refresh.
Private repos
Install the GitHub App on your org or user account and grant access to the repo. The app issues short-lived tokens server-side — nothing goes in the badge URL.
URL = cache key
Each query string is a separate image. Copy the full URL from the builder.
cache range
1h-7d (3600-604800s). Shorter = faster README updates; longer = fewer requests.
limit cap
Max 100 contributors. Up to 100 are fetched from GitHub even when you request fewer.