Progress bars for...
_
Paste a single script tag to embed live progress bars as web components, ASCII art, or plain text. Timezone aware and updated to the second.
~/year-progress2026
<script src="https://api.gru0.dev/progress-bar.js"></script> <progress-bar year></progress-bar>
scroll
// capabilities
Most of what the API can do
One API, a web component, three data formats, and a hosted key-value store for persistent progress bars.
Web component
One script tag, a custom element that works everywhere. Day/year/date-range progress ticks in real time. Custom endpoints via src + refresh.
Hosted store
POST /progress/v1/store returns an id + writeKey. Update anytime with PATCH. The badge URL is stable, embed in READMEs, Notion, static sites.
Multi-bar cards
Single SVG with up to 6 bars via ?bars=Label:value:max|... For dashboards, sprint trackers, status pages.
6 ASCII styles
Blocks, shades, dots, arrows, line, mosaic, unicode art for terminals, CI, and plain text.
CSS themeable
Set color and bg with any CSS color. Respects custom properties and dark mode.
Timezone aware
Pass any IANA timezone via ?tz=. Falls back to proxy headers (auto-detected), then UTC. Day and year respect local boundaries.
Value / max + date ranges
?value=847&max=1000 for custom metrics, ?start=&end= for date ranges. SVG, JSON, text, iframe, ascii from one endpoint.
Live by the second
Every request returns the latest value. No stale cache, no cron jobs.
// playground
Build your embed
Pick the options and copy the snippet.
Progress type
Title
Format
Timezone
Decimals · 2
Styling & Theme
Accent Color
Background Color
preview
Script
<script src="https://api.gru0.dev/progress-bar.js?year" defer></script>Element
<progress-bar year></progress-bar>Script Embed (Recommended): Paste the Script tag anywhere in your HTML. The progress bar will render at that location automatically.Custom Element: For advanced usage, load the script (without parameters) in your head, and place the Element tag where you want it to show.
// styles
Six ASCII styles
Unicode art bars for any plain-text surface. Pass ?style= to pick one.
ASCII · live
blocksdefault · solid fill
?format=ascii&style=blocksshadesgraduated density
?format=ascii&style=shadesdotsbraille dots
?format=ascii&style=dotsarrowsdirectional
?format=ascii&style=arrowslineclassic = / -
?format=ascii&style=linemosaictiled squares
?format=ascii&style=mosaic// reference
Full API documentation
All endpoints, query parameters, and web component docs in one place.
View documentation →Set it up with AI
in one paste
Drop this prompt into your favorite AI agent and get a perfectly styled embed in seconds.
- 01Copy the promptEvery endpoint, parameter, and usage note, ready to go.
- 02Paste into your agentDrop it into any coding AI. No plugins or setup.
- 03Answer a few questionsFormat, style, timezone, then get your exact embed.
CursorClaudeCodex
70 lines
I need a progress bar on my site using https://api.gru0.dev.
The web component
<progress-bar> adapts to any site's theme, reads CSS custom properties (--primary, --accent, --card, --surface, --foreground, --radius, --font-mono, and many more) and respects dark mode, so it blends in by default. Override with color/bg attributes if needed. Default title is "Progress".
## Endpoints
GET /progress/v1?value=847&max=1000 , custom value and max
GET /progress/v1?start=2026-01-01&end=2026-06-30 , date range progress
GET /progress/v1/day , current day progress (0-100), demo/showcase endpoint
GET /progress/v1/year , current year progress (0-100), demo/showcase endpoint
GET /progress/v1/multi?bars=Label1:value1:max1|Label2:value2:max2&label=Card+Title , multi-bar SVG card
## Hosted Progress Store (persistent bars with a write key)
POST /progress/v1/store , create a bar. Body: { "label": "Sprints", "max": 1000, "value": 0, "unit": "tasks", "color": "#6366f1" }. Returns { id, writeKey, badgeUrl }. The writeKey is shown once and used for all updates.
PATCH /progress/v1/store/{id} , update a bar. Requires Authorization: Bearer <writeKey>. Body: { "value": 847 }. Can also update label, max, unit, color, dark.
GET /progress/v1/store/{id} , render a stored bar. Public URL, no auth. Supports all format/style/width/show/color/bg/dark/decimals params. Returns the same output as the main endpoint.
DELETE /progress/v1/store/{id} , delete a bar. Requires Authorization: Bearer <writeKey>.
Web component integration: <progress-bar src="/progress/v1/store/x7k2m?format=json" refresh="60"></progress-bar>. Fetches the same JSON shape: { percent, percentText, label, valueText, meta }.
## Parameters (all optional except bars for /multi)
Single-bar parameters (/progress/v1, /day, /year):
format text | ascii | json | svg default: text
style blocks | shades | dots | arrows | line | mosaic ASCII only, default: blocks
width 10-200 (bar width in characters for ASCII) default: 40
show pct | value | both | none (suffix display for ASCII) default: pct
decimals 0-6 default: 0
label Custom text (max 64 chars)
tz Any IANA timezone, auto-detected via header otherwise
color Bar accent color (any CSS color) SVG only, optional
bg Card background (any CSS color) SVG only, optional
dark true/1 or false/0 for dark/light mode (SVG only, default light)
unit Short label (max 32 chars)
Multi-bar parameters (/progress/v1/multi):
bars (required): pipe-separated list of bar definitions, each in format Label:value:max[:color], max 6 bars
label (optional): card title
color (optional): global accent color for all bars
bg (optional): card background color
dark (optional): true/1 for dark mode
SVG defaults to light mode. Use dark=true for dark mode and dark=false for light mode.
## Web Component
<script src="https://api.gru0.dev/progress-bar.js" defer></script>
<progress-bar value="847" max="1000" label="Sprints" unit="tasks"></progress-bar>
Attributes: value, max, label (title), unit, tz, day, year, color, bg, compact, no-card, src (custom JSON URL), refresh (polling seconds, 1,300).
Real-time: day, year, and date-range progress updates every second. No polling needed.
Custom endpoint: <progress-bar src="https://..." refresh="5"></progress-bar> expects JSON: { percent, percentText, label, valueText, meta }. If the response includes start and end (epoch ms), the bar updates in real time.
JS API: bar.data = { percent: 84.7 } or bar.setProgress(value, max) for instant updates. Returns the element for chaining.
## Usage tips
- The bare text format returns just the number (e.g., "84.70"). ASCII format returns a unicode progress bar. JSON returns structured data with percent, percentText, label, valueText, meta. SVG returns an inline SVG card.
- The web component is a Custom Element, register it once with the <script> tag, then use <progress-bar> anywhere on the page.
- For date-range queries, the start/end format is YYYY-MM-DD. Timezone affects date boundaries for day/year queries.
- The compact attribute removes the card wrapper. no-card removes card styling for custom layouts.
- If both value/max and start/end are omitted, it defaults to day progress (mostly a demo, the real value is in value/max, date-range, stored bars, multi-bar, and the web component).
- Multi-bar cards are perfect for project health dashboards, showing multiple metrics in a single SVG.
Ask clarifying questions ONLY if the user hasn't already specified the required information and the info is important. Assume sensible defaults for non-important missing details (e.g., default to SVG badge for READMEs, web component for websites, a static demo (day/year) if they just want to see it work, respect the website's theme for web components, default to blocks style for ASCII, etc.). Then generate the exact embed code.
For more details, check the full docs at https://progress.gru0.dev/docs/.