Dynamic SVG widgets for GitHub, ready to embed into your README
Explore the docs »
Report Bug
·
Request Feature
Open the official widget builder at github-widgets.kretoffer.com, pick a widget, customize it, and copy the generated snippet into your README.md. That's it.
A roadmap card generated from repository issues, with status badges (open/closed), labels and a custom heading.
| Parameter | Default | Description |
|---|---|---|
count |
20 |
Number of issues to show |
header-text |
Roadmap |
Card heading text |
width |
500 |
Card width in px, 300 – 1600 |
theme |
default |
Predefined widget theme |
labels |
true |
Show labels on issue card |
closed |
false |
Show closed issues |
animation-duration |
0.7 |
Time in seconds (s) for one issue to appear, not the whole animation. Issues appear one by one; total animation time = animation-duration × number of issues. 0 — no animation |
A stats card for any GitHub user: stars, commits, PRs, issues, followers and more, split into responsive columns.
| Parameter | Default | Description |
|---|---|---|
columns |
1 |
Number of columns, 1 – 4; auto picks ceil(sqrt(count)) |
width |
500 |
Card width in px, 300 – 1600 |
theme |
default |
Predefined widget theme |
animation-duration |
0.7 |
Time in seconds (s) for one metric to appear. 0 — no animation |
Each metric can be toggled with a show-{key} parameter, true by default:
| Key | Query param | Metric |
|---|---|---|
stars |
show-stars |
Total stars |
commits |
show-commits |
Total commits |
commits-year |
show-commits-year |
Commits this year |
prs |
show-prs |
Total pull requests |
issues |
show-issues |
Total issues |
repos |
show-repos |
Total repositories |
contributed |
show-contributed |
Repositories contributed to |
followers |
show-followers |
Followers |
following |
show-following |
Following |
forks |
show-forks |
Total forks |
starred |
show-starred |
Repos starred |
merged-prs |
show-merged-prs |
Merged pull requests |
Example hiding two metrics:
A skill table card with Simple Icons logos, grouped into sections, for your tech stack.
The skills parameter is a |-separated list of items. A token wrapped in -- on both sides (e.g. --Programming Languages--) becomes a section header. A plain slug (e.g. python) renders the matching Simple Icons logo with a pretty title. Use Title:slug (e.g. FastAPI:fastapi) to set a custom title for a slug.
| Parameter | Default | Description |
|---|---|---|
skills |
— | Required. ` |
header-text |
— | Card heading text |
columns |
4 |
Number of columns, 1 – 10 |
show-titles |
true |
Show captions under icons |
icon-size |
48 |
Icon size in px, 16 – 128 |
use-original-colors |
true |
Use brand colors from Simple Icons; false falls back to the theme text color |
icon-color |
— | Override icon color for all tiles (e.g. #e6edf3) |
gap |
16 |
Gap between tiles in px, 0 – 64 |
width |
500 |
Card width in px, 300 – 1600 |
theme |
default |
Predefined widget theme |
animation-duration |
0.6 |
Time in seconds (s) for one element to appear. 0 — no animation |
Run your own instance with Docker:
docker run -e GITHUB_TOKEN=your_token -p 8000:8000 ghcr.io/kretoffer/github-widgets:latestRequired environment variables (see .env.example):
GITHUB_TOKEN— GitHub token used to fetch repository data
Then point your embeds to your own host instead of the public instance.
uv sync --all-groups
uv run github-widgetsQuality checks:
uv run ruff check
uv run pyright
uv run pytestProject layout:
src/
├── api/ # FastAPI routes
├── schemas/ # Pydantic models
├── templates/ # SVG templates
└── tools/ # GitHub API and render logic