Guide / Controls / Readouts

Ring

How far along something is

When to use it. A determinate progress indicator (circular ring or linear bar). Read-only.

Type
progressRing
Also titled
Progress Ring
Default size
2 rows × 2 columns
Symbol
circle.dashed
Docs
Docs complete
Search for it as
  • ring
  • progress
  • circle
  • completion
  • percent
  • activity ring
Ring: Circular download progress
Rendered by the app

Fields

15 fields you can set on a progressRing control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
Motionanimationchoiceone of 5—

How the ring moves when the number changes

The fill eases to each new value; instant jumps with no travel.

  • smoothan even ease and the default
  • snappya quick move that settles fast
  • bouncyovershoots slightly then springs back
  • gentlea slow and soft glide
  • instantjumps straight to the new value with no travel
Lowest valueminnumber0

The value that shows an empty ring

Sets the value at 0% fill, in the control's unit (e.g. 0).

Highest valuemaxnumber100

The value that shows a full ring

Sets the value at 100% fill, in the control's unit (e.g. 100).

ShapeprogressStylechoiceone of 2ring

Round ring or flat bar

Switches the display between a circular ring and a horizontal bar.

  • ring defaulta circular ring with the number in the middle
  • bara thin horizontal bar with the title and number above
GlowglowRadiusnumber0–30 ptstep 10

A 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 endslineCapchoiceone of 3round

The shape of the fill's ends

Rounds, flattens or squares the ends of the ring or the bar corners.

  • round defaultsoft rounded ends
  • buttflat ends cut exactly at the value
  • squareflat ends that stick out half a stroke past the value
Colortintcolor#667eea

The colour of the filled part

Paints the fill in this colour (e.g. green #34C759).

Color zonescolorByValuelist—

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.

Titlelabeltext—

The words on the control

Shows this text in the middle of the ring or above the bar.

Symbolicontext—

A small picture in the ring

Draws this SF Symbol in the centre of the ring; a bar ignores it.

ThicknessarcThicknessnumber2–40 ptstep 1—

How heavy the stroke is

Sets ring stroke width or bar height in points, 2 to 40; unset scales with the size.

Bar roundnessbarCornerRadiusnumber0–30 ptstep 14

How round the bar's corners are

Rounds the bar's corners by this many points, 0 to 30 (4 by default).

Hide the numberhideValueon / offfalse (off)

Arc only, no number

Removes the centre number when on, leaving just the arc.

Look aheadforecastchoiceone 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.

  • countdownthe value is a time and the control counts down to it
  • reachthe value is expected to arrive at a target number or to keep changing at a set rate
Unitunittext—

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
TakesFromTypeWhat it does
valueshowhub, mqtt, http, sensor, store, derive, defaultnumber

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.

  • 40 then 75

Examples

10 examples, each one a control you can paste into a layout.

Circular download progress

Demonstrates the default ring with a tint, a center icon and a label, filling as a live firmware percentage arrives.

JSON 12 lines
{
  "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

Ring: Circular download progress
Rendered by the app

Linear bar (washer cycle)

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
{
  "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

Ring: Linear bar (washer cycle)
Rendered by the app

Dial look

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.

Color zones

Demonstrates colorByValue: the ring turns red, amber or green depending on which zone the battery level falls in, overriding tint.

JSON 9 lines
{
  "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

Quiet look: arc only

Demonstrates hideValue: true (the Quiet look): the center number disappears and only the arc shows, handy as a compact glyph.

JSON 7 lines
{
  "type": "progressRing",
  "id": "quiet-ring",
  "position": [0, 0],
  "label": "Progress",
  "hideValue": true
}

Open in CAR-TER

Ring: Quiet look: arc only
Rendered by the app

Glow, line ends and thickness

Demonstrates glowRadius: 12 adding a soft halo, lineCap: "butt" cutting the ring ends flat and arcThickness: 16 making a heavier stroke.

JSON 10 lines
{
  "type": "progressRing",
  "id": "glow-ring",
  "position": [0, 0],
  "label": "Goal",
  "tint": "#5AC8FA",
  "glowRadius": 12,
  "lineCap": "butt",
  "arcThickness": 16
}

Open in CAR-TER

Ring: Glow, line ends and thickness
Rendered by the app

Bar roundness and motion

Demonstrates barCornerRadius: 0 squaring the bar's corners and animation: "bouncy" making the fill overshoot and settle on each change.

JSON 9 lines
{
  "type": "progressRing",
  "id": "square-bar",
  "position": [0, 0],
  "progressStyle": "bar",
  "barCornerRadius": 0,
  "animation": "bouncy",
  "label": "Upload"
}

Open in CAR-TER

Ring: Bar roundness and motion
Rendered by the app

Converted unit

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
{
  "type": "progressRing",
  "id": "oven-temp",
  "position": [0, 0],
  "min": 0,
  "max": 250,
  "unit": "celsius",
  "label": "Oven"
}

Open in CAR-TER

Ring: Converted unit
Rendered by the app

Forecast: countdown

Demonstrates forecast: "countdown": the value is a time, so the widget counts down to it between real readings.

JSON 7 lines
{
  "type": "progressRing",
  "id": "timer-ring",
  "position": [0, 0],
  "label": "Timer",
  "forecast": "countdown"
}

Open in CAR-TER

Ring: Forecast: countdown
Rendered by the app

Forecast: reach a target at a time

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
{
  "type": "progressRing",
  "id": "charge-ring",
  "position": [0, 0],
  "label": "Charge",
  "forecast": "reach",
  "forecastTarget": 100,
  "forecastTimeFrom": "eta"
}

Open in CAR-TER

Ring: Forecast: reach a target at a time
Rendered by the app

Forecast: keep moving at a rate

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
{
  "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.

Ring: Forecast: keep moving at a rate
Rendered by the app

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.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Circular download progress” on your phone.

    carterkit demo progressRing --example 'Circular download progress'
  3. 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.