Widget Jauge

Une valeur sur un cadran entre un minimum et un maximum fixes. Idéal pour les SLO, les budgets d'erreur, les températures et la capacité.

The gauge template draws a value on an arc between two bounds you choose. It answers "how close to the limit is this?", which a bare number cannot: 2.4 means nothing until you know the ceiling is 5.

Fields

Field	Type	Notes
`template`	string	Required. Must be `"gauge"`
`value`	float	Required. Must be finite and fall within `min_value` – `max_value`; outside that range the request is rejected with `422`
`min_value`	float	Required. Start of the arc. Must be strictly less than `max_value`
`max_value`	float	Required. End of the arc
`unit`	string	Appended to the value and to the MIN / MAX end labels. Max 32 characters
`trend`	string	`up` / `down` / `flat`. Accepted by the server; the current iOS gauge does not draw an arrow, so treat it as forward-looking metadata rather than something users will see
`label`, `subtitle`, `icon`, `accent_color`, `background_color`, `text_color`	string	Shared content fields — see the API reference

Example: error rate against an SLO

PATCH /widgets/error-rate

{
  "content": {
    "template": "gauge",
    "value": 2.4,
    "min_value": 0,
    "max_value": 5,
    "unit": "%",
    "label": "Errors",
    "subtitle": "api-gateway · last 5m · SLO 1.0%",
    "icon": "chart.line.uptrend.xyaxis",
    "accent_color": "red"
  }
}

Behavior

Pick bounds once and keep them fixed. The arc's meaning comes entirely from where the needle sits between them, so a max_value that tracks the current peak makes every update look the same and hides exactly the trend you built the widget to see. Choose the number that means "this is the limit" — the SLO, the disk size, the tank capacity — and leave it alone.

Because the server rejects a value outside the bounds, a metric that can legitimately overshoot needs headroom in max_value rather than a clamp at the sender. Set the ceiling above the worst case you expect, or keep sending the raw number to a value widget and let the subtitle carry the threshold.

ℹ Info

The MIN and MAX end labels take the same unit as the value, so a unit that reads well next to a big number ("%", "°C") also has to read well in MAX 5%. Long words ("requests per second") are better placed in label or subtitle.

For a fraction that is already a percentage of a known whole, progress says the same thing with less configuration.

Bientôt dans la version 1.6 de l'app

Cette section décrit une fonctionnalité d'une mise à jour de l'app en attente de validation par l'App Store. Elle se déverrouille ici automatiquement dès que la mise à jour est disponible.

Set the bounds and drag the needle on the playground to see the arc across the small, medium, large, and Lock Screen families.