Fields 15 fields you can set on a progressRing control. Every control also takes the shared fields (id, position, span, sync, action).
Fields Field Type Default What it does Motion animationchoice one of 5 — How the ring moves when the number changes
The fill eases to each new value; instant jumps with no travel.
smooth an even ease and the default snappy a quick move that settles fast bouncy overshoots slightly then springs back gentle a slow and soft glide instant jumps straight to the new value with no travel Lowest value minnumber 0The value that shows an empty ring
Sets the value at 0% fill, in the control's unit (e.g. 0).
Highest value maxnumber 100The value that shows a full ring
Sets the value at 100% fill, in the control's unit (e.g. 100).
Shape progressStylechoice one of 2 ringRound ring or flat bar
Switches the display between a circular ring and a horizontal bar.
ring default a circular ring with the number in the middle bar a thin horizontal bar with the title and number above Glow glowRadiusnumber 0–30 pt step 1 0A soft halo around the fill
Adds a glow of this many points (0 to 30) behind the fill in its own colour; 0 is none.
Line ends lineCapchoice one of 3 roundThe shape of the fill's ends
Rounds, flattens or squares the ends of the ring or the bar corners.
round default soft rounded ends butt flat ends cut exactly at the value square flat ends that stick out half a stroke past the value Color tintcolor #667eeaThe colour of the filled part
Paints the fill in this colour (e.g. green #34C759).
Color zones colorByValuelist — Colour the ring by how far along it is
The fill changes colour as the value crosses each limit, e.g. red to 30 then amber to 70 then green.
Title labeltext — The words on the control
Shows this text in the middle of the ring or above the bar.
Symbol icontext — A small picture in the ring
Draws this SF Symbol in the centre of the ring; a bar ignores it.
Thickness arcThicknessnumber 2–40 pt step 1 — How heavy the stroke is
Sets ring stroke width or bar height in points, 2 to 40; unset scales with the size.
Bar roundness barCornerRadiusnumber 0–30 pt step 1 4How round the bar's corners are
Rounds the bar's corners by this many points, 0 to 30 (4 by default).
Hide the number hideValueon / off false (off) Arc only, no number
Removes the centre number when on, leaving just the arc.
Look ahead forecastchoice one of 2 — Show as a countdown, or show where the value is expected to reach
Keeps moving the fill by this much per second, -1000 to 1000, from the last real reading.
countdown the value is a time and the control counts down to it reach the value is expected to arrive at a target number or to keep changing at a set rate Unit unittext — What the number is measured in
Shows the number in the viewer's local unit, e.g. celsius reads 356°F in the US; min and max stay in that unit.
Emits and receives What this control sends when you use it, and what it can show or follow when data arrives.
Receives Receives Takes From Type What it does value showhub, mqtt, http, sensor, store, derive, default number a number between the lowest and highest value
the ring or bar fills to it; a value past either end sits at that end
Example: 40
Sample The placeholder value the editor shows before real data arrives.
Examples 10 examples, each one a control you can paste into a layout.
Demonstrates the default ring with a tint, a center icon and a label, filling as a live firmware percentage arrives.
JSON 12 lines Copy {
"type": "progressRing",
"id": "download-progress",
"position": [0, 0],
"min": 0,
"max": 100,
"progressStyle": "ring",
"tint": "#34C759",
"label": "Download",
"icon": "arrow.down.circle",
"sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "task": "firmware_update" }, "valuePath": "percent" }]
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates progressStyle: "bar" (the Bar look): a horizontal bar with the title and number above it, filling over a 90-minute cycle.
JSON 12 lines Copy {
"type": "progressRing",
"id": "washer-cycle",
"position": [2, 0],
"span": [1, 4],
"min": 0,
"max": 90,
"progressStyle": "bar",
"tint": "#5AC8FA",
"label": "Washer Cycle (min)",
"sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "device": "washer" }, "valuePath": "elapsed_minutes" }]
}Open in CAR-TER ↗
Rendered by the app Light Dark The Dial look turns this control into a gauge (type: "gauge", gaugeStyle: "half"), so it is not a Progress Ring any more; see Unit for its fields and examples.
Demonstrates colorByValue: the ring turns red, amber or green depending on which zone the battery level falls in, overriding tint.
JSON 9 lines Copy {
"type": "progressRing",
"id": "battery-ring",
"position": [0, 0],
"min": 0,
"max": 100,
"label": "Battery",
"colorByValue": [{ "limit": 20, "color": "#FF3B30" }, { "limit": 50, "color": "#FF9500" }, { "limit": 100, "color": "#34C759" }]
}Open in CAR-TER ↗
Demonstrates hideValue: true (the Quiet look): the center number disappears and only the arc shows, handy as a compact glyph.
JSON 7 lines Copy {
"type": "progressRing",
"id": "quiet-ring",
"position": [0, 0],
"label": "Progress",
"hideValue": true
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates glowRadius: 12 adding a soft halo, lineCap: "butt" cutting the ring ends flat and arcThickness: 16 making a heavier stroke.
JSON 10 lines Copy {
"type": "progressRing",
"id": "glow-ring",
"position": [0, 0],
"label": "Goal",
"tint": "#5AC8FA",
"glowRadius": 12,
"lineCap": "butt",
"arcThickness": 16
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates barCornerRadius: 0 squaring the bar's corners and animation: "bouncy" making the fill overshoot and settle on each change.
JSON 9 lines Copy {
"type": "progressRing",
"id": "square-bar",
"position": [0, 0],
"progressStyle": "bar",
"barCornerRadius": 0,
"animation": "bouncy",
"label": "Upload"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates unit: "celsius": the value arrives in °C but the readout shows 356°F in the US for 180; min and max stay in °C so the fill looks the same everywhere.
JSON 9 lines Copy {
"type": "progressRing",
"id": "oven-temp",
"position": [0, 0],
"min": 0,
"max": 250,
"unit": "celsius",
"label": "Oven"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates forecast: "countdown": the value is a time, so the widget counts down to it between real readings.
JSON 7 lines Copy {
"type": "progressRing",
"id": "timer-ring",
"position": [0, 0],
"label": "Timer",
"forecast": "countdown"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates forecast: "reach" with forecastTarget and forecastTimeFrom: the ring moves toward 100 so it arrives when the eta control says; a real value replaces the guess.
JSON 9 lines Copy {
"type": "progressRing",
"id": "charge-ring",
"position": [0, 0],
"label": "Charge",
"forecast": "reach",
"forecastTarget": 100,
"forecastTimeFrom": "eta"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates forecast: "reach" with forecastRate: 0.5: with no arrival time, the ring keeps climbing half a unit per second from the last real reading.
JSON 8 lines Copy {
"type": "progressRing",
"id": "rate-ring",
"position": [0, 0],
"label": "Print",
"forecast": "reach",
"forecastRate": 0.5
}Open in CAR-TER ↗
Note: this control is read-only: it has no action, long-press or detail view, so there are no examples for them. Its theme fields (corner roundness, spacing, colors, border, title size) restyle it through the layout theme like every control.
Rendered by the app Light Dark Try it on your phone carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.
Install the Python kit.
Copy pip install carterkit Show “Circular download progress” on your phone.
Copy carterkit demo progressRing --example 'Circular download progress' Swap in any example name from this page, or leave --example off for the first one.
carterkit quickstart · Get CAR-TER
Styles
"ring" (default)
Circular progress ring with percentage and optional label/icon in the center. The
stroke, number, icon, and label all scale to the ring's size, so a small cell stays
tight and a large one reads bold. Square aspect (1:1) — give it ~3 rowSpan in a
2-D grid. Set hideValue (and hideBackground) for a bare ring glyph. See Grid Dimensions .
"bar"
Linear progress bar (thin horizontal bar). Header shows label and percentage.
Behavior
Progress animates smoothly between value updates
Percentage is calculated as (value - min) / (max - min) * 100
No action — display only
Shadow opacity — Base fields
Sync — Value updates
Unit — For when you want a range indicator rather than progress
Generated from ControlDocs/progress-ring.md. Something unclear or missing? Tell me .