Guide / Controls / Readouts

Dial

A number on a dial, from low to high

When to use it. A circular arc dial showing a synced numeric value within a range. Read-only.

Type
gauge
Also titled
Gauge
Default size
2 rows × 2 columns
Symbol
gauge.medium
Docs
Docs complete
Search for it as
  • dial
  • meter
  • speedometer
  • level
  • needle
  • progress
Dial: Temperature gauge with color zones
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
Motionanimationchoiceone of 5—

How the dial moves when the number changes

The needle or arc 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

Where the dial starts

The value shown at the empty end of the arc, in the gauge's unit (e.g. 0).

Highest valuemaxnumber100

Where the dial fills up

The value shown at the full end of the arc; readings at or above it fill the arc completely.

ShapegaugeStylechoiceone of 2half

Half dial or full ring

Switches between a wide 180° half dial and a 360° square ring.

  • half defaulta half-circle dial that is wide and short
  • fulla closed ring that is square
GlowglowRadiusnumber0–30 ptstep 10

A soft halo around the fill

Adds a glow behind the value arc, 0 (off) to 30 points wide.

Line endslineCapchoiceone of 3round

The shape of the arc's ends

Rounds, flattens or squares the ends of the track and the filled arc.

  • round defaultsoft rounded ends
  • buttflat ends cut exactly at the value
  • squareflat ends that stick out half a stroke past the value
Color zonessegmentslist—

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 blendingcolorBlendnumber0–1step 0.050

Hard bands or a smooth fade between colors

Softens the color changes between zones, from 0 (sharp steps) to 1 (one smooth gradient).

Colortintcolor#667eea

The color of the filled arc

Paints the filled part of the arc in one color when there are no color zones.

Titlelabeltext—

The caption under the dial

Shows this text beneath the gauge in the title text size.

Symbolicontext—

A small picture in the middle

Draws the chosen SF Symbol in the center of the dial next to the number.

Decimal placesstepnumber1

How 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 lengtharcAnglenumber1–360step 1180

How much of a circle the arc covers

Sets the sweep of the arc from 1° to 360°; 270 gives a three-quarter dial.

Arc turnarcRotationnumber-180–180step 10

Where the arc begins around the circle

Rotates the whole arc by -180° to 180° so its gap sits elsewhere.

Arc thicknessarcThicknessnumber1–40 ptstep 1auto

How fat the arc stroke is

Sets the stroke width from 1 to 40 points; left empty it scales with the gauge size.

Hide the numberhideValueon / offfalse (off)

Dial only, no number

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

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

  • countdownthe value is a time; the dial 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 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
TakesFromTypeWhat it does
valueshowhub, mqtt, http, sensor, store, derive, defaultnumber

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.

  • 40 then 75

Examples

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

Temperature gauge with color zones

Demonstrates segments: the arc turns green, amber or red depending on which zone the live CPU temperature falls in.

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

Dial: Temperature gauge with color zones
Rendered by the app

Full circle gauge (battery level)

Demonstrates a full ring with a single tint and a center icon, reading a live battery percentage.

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

Dial: Full circle gauge (battery level)
Rendered by the app

Gauge with long-press detail

Demonstrates longPressGroup: holding the dial opens a popup with a history sparkline and min/max labels.

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

Dial: Gauge with long-press detail
Rendered by the app

Ring look (full circle)

Demonstrates the Ring look: gaugeStyle: "full" closes the dial into a square 360° ring, with the title under it.

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

Dial: Ring look (full circle)
Rendered by the app

Bar look

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.

Smooth color blend and bold look

Demonstrates colorBlend: 1 turning the zones into one gradient, with arcThickness: 16 (the Bold look) for a heavier stroke.

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

Dial: Smooth color blend and bold look
Rendered by the app

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 12 lines
{
  "type": "gauge",
  "id": "quiet-demo",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 100,
  "hideValue": true,
  "tint": "#34C759"
}

Open in CAR-TER

Dial: Quiet look: arc only
Rendered by the app

Glow and line ends

Demonstrates glowRadius: 12 adding a soft halo and lineCap: "butt" cutting the arc ends flat.

JSON 14 lines
{
  "type": "gauge",
  "id": "glow-demo",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 100,
  "glowRadius": 12,
  "lineCap": "butt",
  "tint": "#00D4FF",
  "label": "Signal"
}

Open in CAR-TER

Dial: Glow and line ends
Rendered by the app

Custom arc shape

Demonstrates arcAngle: 270, arcRotation: 0 and animation: "bouncy": a three-quarter dial whose needle overshoots and settles on each change.

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

Dial: Custom arc shape
Rendered by the app

Converted unit

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
{
  "type": "gauge",
  "id": "unit-demo",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 40,
  "unit": "celsius",
  "step": 0,
  "label": "Outside"
}

Open in CAR-TER

Dial: 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 12 lines
{
  "type": "gauge",
  "id": "countdown-demo",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 3600,
  "forecast": "countdown",
  "label": "Oven ready"
}

Open in CAR-TER

Dial: Forecast: countdown
Rendered by the app

Forecast: reach a target at a time

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
{
  "type": "gauge",
  "id": "charge-demo",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 100,
  "forecast": "reach",
  "forecastTarget": 100,
  "forecastTimeFrom": "eta",
  "label": "Charging"
}

Open in CAR-TER

Dial: 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 dial keeps climbing 0.5 per second from the last real reading.

JSON 13 lines
{
  "type": "gauge",
  "id": "rate-demo",
  "position": [
    0,
    0
  ],
  "min": 0,
  "max": 100,
  "forecast": "reach",
  "forecastRate": 0.5,
  "label": "Tank fill"
}

Open in CAR-TER

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

Themed gauge

Demonstrates the theme fields: rounder corners, more inner spacing, a custom background, border and larger title text.

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

Dial: Themed gauge
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 “Temperature gauge with color zones” on your phone.

    carterkit demo gauge --example 'Temperature gauge with color zones'
  3. 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.