Fields 18 fields you can set on a gauge 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 dial moves when the number changes
The needle or arc 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 0Where the dial starts
The value shown at the empty end of the arc, in the gauge's unit (e.g. 0).
Highest value maxnumber 100Where the dial fills up
The value shown at the full end of the arc; readings at or above it fill the arc completely.
Shape gaugeStylechoice one of 2 halfHalf dial or full ring
Switches between a wide 180° half dial and a 360° square ring.
half default a half-circle dial that is wide and short full a closed ring that is square Glow glowRadiusnumber 0–30 pt step 1 0A soft halo around the fill
Adds a glow behind the value arc, 0 (off) to 30 points wide.
Line ends lineCapchoice one of 3 roundThe shape of the arc's ends
Rounds, flattens or squares the ends of the track and the filled arc.
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 zones segmentslist — Colors for different ranges of values
The arc changes color as the value crosses each limit, e.g. green to 60 then amber to 80 then red.
Zone blending colorBlendnumber 0–1 step 0.05 0Hard bands or a smooth fade between colors
Softens the color changes between zones, from 0 (sharp steps) to 1 (one smooth gradient).
Color tintcolor #667eeaThe color of the filled arc
Paints the filled part of the arc in one color when there are no color zones.
Title labeltext — The caption under the dial
Shows this text beneath the gauge in the title text size.
Symbol icontext — A small picture in the middle
Draws the chosen SF Symbol in the center of the dial next to the number.
Decimal places stepnumber 1How many digits after the point
Sets the rounding of the center number, e.g. 1 shows 72.5 and 0.1 shows 72.54.
Arc length arcAnglenumber 1–360 step 1 180How much of a circle the arc covers
Sets the sweep of the arc from 1° to 360°; 270 gives a three-quarter dial.
Arc turn arcRotationnumber -180–180 step 1 0Where the arc begins around the circle
Rotates the whole arc by -180° to 180° so its gap sits elsewhere.
Arc thickness arcThicknessnumber 1–40 pt step 1 autoHow fat the arc stroke is
Sets the stroke width from 1 to 40 points; left empty it scales with the gauge size.
Hide the number hideValueon / off false (off) Dial only, no number
Removes the center number when on, leaving just the arc.
Look ahead forecastchoice one of 2 — A guess drawn beside the real reading
Keeps moving the dial by this much per second, -1000 to 1000, from the last real reading.
countdown the value is a time; the dial 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 70.7°F in the US.
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 to point the dial at
the arc and number glide to it; a value past either end sits at that end, and anything that is not a number shows the lowest value
Example: 40
Sample The placeholder value the editor shows before real data arrives.
Examples 13 examples, each one a control you can paste into a layout.
Demonstrates segments: the arc turns green, amber or red depending on which zone the live CPU temperature falls in.
JSON 16 lines Copy {
"type": "gauge",
"id": "cpu-temp",
"position": [0, 0],
"min": 30,
"max": 100,
"gaugeStyle": "half",
"label": "CPU Temp",
"icon": "thermometer.medium",
"segments": [
{ "limit": 60, "color": "#34C759" },
{ "limit": 80, "color": "#FF9500" },
{ "limit": 100, "color": "#FF3B30" }
],
"sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "device": "server" }, "valuePath": "cpu_temp" }]
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates a full ring with a single tint and a center icon, reading a live battery percentage.
JSON 12 lines Copy {
"type": "gauge",
"id": "battery",
"position": [0, 2],
"min": 0,
"max": 100,
"gaugeStyle": "full",
"tint": "#34C759",
"icon": "battery.100",
"label": "Battery",
"sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "device": "rover" }, "valuePath": "battery_pct" }]
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates longPressGroup: holding the dial opens a popup with a history sparkline and min/max labels.
JSON 22 lines Copy {
"type": "gauge",
"id": "room-temp",
"position": [0, 0],
"min": 50,
"max": 100,
"gaugeStyle": "half",
"label": "Living Room",
"sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "room": "living" }, "valuePath": "temperature" }],
"longPressGroup": {
"position": [0, 0],
"span": [2, 2],
"id": "temp-detail",
"label": "Temperature History",
"grid": { "columns": 2, "rows": 2 },
"children": [
{ "type": "sparkline", "id": "temp-history", "position": [0, 0], "span": [1, 2], "tint": "#FF6B6B", "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "room": "living" }, "valuePath": "temperature" }] },
{ "type": "label", "id": "temp-min", "position": [1, 0], "text": "Min: --" },
{ "type": "label", "id": "temp-max", "position": [1, 1], "text": "Max: --" }
]
}
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates the Ring look: gaugeStyle: "full" closes the dial into a square 360° ring, with the title under it.
JSON 17 lines Copy {
"type": "gauge",
"id": "ring-demo",
"position": [
0,
0
],
"span": [
2,
3
],
"min": 0,
"max": 100,
"gaugeStyle": "full",
"label": "Disk used",
"tint": "#667eea"
}Open in CAR-TER ↗
Rendered by the app Light Dark The Bar look swaps the control for a progress bar that fills left to right: the editor
changes the control's type to progressRing with progressStyle: "bar", so the example
lives in Unit (its "Bar" example); a gauge document only carries gauge examples.
Demonstrates colorBlend: 1 turning the zones into one gradient, with arcThickness: 16 (the Bold look) for a heavier stroke.
JSON 2 lines Copy { "type": "gauge", "id": "blend-demo", "position": [0, 0], "min": 0, "max": 100, "label": "Load", "arcThickness": 16, "colorBlend": 1,
"segments": [ { "limit": 50, "color": "#34C759" }, { "limit": 80, "color": "#FF9500" }, { "limit": 100, "color": "#FF3B30" } ] }Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates hideValue: true (the Quiet look): the center number disappears and only the arc shows, handy as a compact glyph.
JSON 12 lines Copy {
"type": "gauge",
"id": "quiet-demo",
"position": [
0,
0
],
"min": 0,
"max": 100,
"hideValue": true,
"tint": "#34C759"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates glowRadius: 12 adding a soft halo and lineCap: "butt" cutting the arc ends flat.
JSON 14 lines Copy {
"type": "gauge",
"id": "glow-demo",
"position": [
0,
0
],
"min": 0,
"max": 100,
"glowRadius": 12,
"lineCap": "butt",
"tint": "#00D4FF",
"label": "Signal"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates arcAngle: 270, arcRotation: 0 and animation: "bouncy": a three-quarter dial whose needle overshoots and settles on each change.
JSON 15 lines Copy {
"type": "gauge",
"id": "arc-demo",
"position": [
0,
0
],
"min": 0,
"max": 8000,
"arcAngle": 270,
"arcRotation": 0,
"animation": "bouncy",
"step": 0,
"label": "RPM"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates unit: "celsius": the value arrives in °C but reads 70.7°F in the US; min and max stay in °C so the arc looks the same everywhere.
JSON 13 lines Copy {
"type": "gauge",
"id": "unit-demo",
"position": [
0,
0
],
"min": 0,
"max": 40,
"unit": "celsius",
"step": 0,
"label": "Outside"
}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 12 lines Copy {
"type": "gauge",
"id": "countdown-demo",
"position": [
0,
0
],
"min": 0,
"max": 3600,
"forecast": "countdown",
"label": "Oven ready"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates forecast: "reach" with forecastTarget and forecastTimeFrom: the dial moves toward 100 so it arrives when the eta control says; a real value replaces the guess.
JSON 14 lines Copy {
"type": "gauge",
"id": "charge-demo",
"position": [
0,
0
],
"min": 0,
"max": 100,
"forecast": "reach",
"forecastTarget": 100,
"forecastTimeFrom": "eta",
"label": "Charging"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates forecast: "reach" with forecastRate: 0.5: with no arrival time, the dial keeps climbing 0.5 per second from the last real reading.
JSON 13 lines Copy {
"type": "gauge",
"id": "rate-demo",
"position": [
0,
0
],
"min": 0,
"max": 100,
"forecast": "reach",
"forecastRate": 0.5,
"label": "Tank fill"
}Open in CAR-TER ↗
Rendered by the app Light Dark Demonstrates the theme fields: rounder corners, more inner spacing, a custom background, border and larger title text.
JSON 2 lines Copy { "type": "gauge", "id": "theme-demo", "position": [0, 0], "min": 0, "max": 100, "label": "Humidity",
"theme": { "cornerRadius": 20, "controlPadding": 12, "surfacePrimary": "#1C1C2E", "accentColor": "#34C759", "foregroundColor": "#FFFFFF", "secondaryColor": "#FFFFFF99", "borderColor": "#34C75966", "borderWidth": 2, "labelFontSize": 16 } }Open in CAR-TER ↗
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 “Temperature gauge with color zones” on your phone.
Copy carterkit demo gauge --example 'Temperature gauge with color zones' Swap in any example name from this page, or leave --example off for the first one.
carterkit quickstart · Get CAR-TER
Gauge Segments
Color zones that change based on the current value:
"segments": [
{ "limit": 60, "color": "#00FF00" },
{ "limit": 80, "color": "#FFAA00" },
{ "limit": 100, "color": "#FF0000" }
]
Each segment fills from the previous segment's limit (or min) up to its own limit. The arc is colored according to which segment the value falls within.
Behavior
Value animates smoothly between updates (smooth profile)
Center displays the numeric value with animated content transition
No action — display only (use Long Press for interaction)
On-control editing (C6)
The dial publishes its arc as a value axis (publishValueAxis) and parts label (title), hideValue (number) and tint (arc fill) via publishPart; zone dots in edit mode ride the arc and snap to other zone limits, the ends and 0. See SharedEditorContract.swift.
Generated from ControlDocs/gauge.md. Something unclear or missing? Tell me .