Gauge¶
Circular or semicircular gauge with needle and colored ranges (NUM-103).

Indicators, analog · Widget catalog · API reference ·
schema gauge.schema.json
Example¶
The traits of the picture above:
ai.Gauge(
value=72,
label="Gauge",
unit="bar",
peak_hold=True,
ranges=[
{"from": 0, "to": 60, "color": "#86efac"},
{"from": 60, "to": 85, "color": "#fde047"},
{"from": 85, "to": 100, "color": "#fca5a5"},
],
size=(180, 180),
)
Traits¶
| Trait | Type | Default | Set by | Description |
|---|---|---|---|---|
mode |
"control", "indicator" |
"indicator" |
host | "control": the user sets the value; "indicator": display only. |
variant |
"circular", "semicircular" |
"circular" |
host | |
ranges |
array of object | [] |
host | Colored ranges drawn on the scale; unsafe colors are ignored (SEC-002). |
setpoint |
number or null | null |
host | Setpoint drawn as a second, dashed pointer with a hollow marker, and stated in the text alternative; null: none (IND-116). |
Common traits (37), shared with other widgets
| Trait | Type | Default | Set by | Description |
|---|---|---|---|---|
label |
string | "" |
host | Plain text, never interpreted as HTML (SEC-002). |
disabled |
boolean | false |
host | Greyed out, input rejected. |
visible |
boolean | true |
host | |
tooltip |
string | "" |
host | Plain text shown on hover. |
size |
array | [160,160] |
host | [width, height] in CSS pixels. |
style |
"modern", "classic", "system" |
"modern" |
host | |
theme |
"auto", "light", "dark", "system" |
"auto" |
host | "auto": the style decides; "system": the host page or the operating system (STYLE-007). |
skin |
object | {} |
host | Replaceable drawing parts: part name -> SVG source, sanitized (STYLE-005, STYLE-006). |
value |
number | 0 |
host, widget | Current value. Set by the host, or by the user in control mode. Shown clamped to [min, max] when coerce is set (NUM-006, NUM-010). |
min |
number | 0 |
host | Lower end of the scale; must be below max, and > 0 on a log scale. |
max |
number | 100 |
host | Upper end of the scale. |
step |
number | 0 |
host | Values entered by the user snap to min + k * step; 0: no snapping (NUM-005). |
unit |
string | "" |
host | |
scale |
"linear", "log" |
"linear" |
host | |
ticks |
integer | 5 |
host | Major scale intervals. |
minor_ticks |
integer | 4 |
host | Minor subdivisions per major interval. |
format |
string | "%.1f" |
host | printf-like spec: %.2f, %.3e, %.3g, %.3n (engineering), %.3s (SI prefix) (NUM-004); %X, %x, %b, %o show the value as a hexadecimal, binary or octal integer, with an optional width padded with zeros such as %04X (IND-110), and values are then typed in that base. |
coerce |
boolean | false |
host | Clamp values to [min, max] instead of rejecting typed values outside it (NUM-010). |
update_rate |
number | 30 |
host | Maximum rate of intermediate values sent while dragging, in Hz (NUM-009). |
entry |
boolean | true |
host | Editable value field in control mode (API-014). |
animate |
boolean | false |
host | |
animation_ms |
integer | 200 |
host | |
value_labels |
array of object | [] |
host | Named values, sorted by value (IND-118): the scale shows the labels instead of numbers, the readout the label of the current value (within 1e-9 of the span), and the value field accepts a label (case ignored). |
lolo |
number or null | null |
host | Low-low alarm limit (ALARM-001). |
lo |
number or null | null |
host | Low alarm limit. |
hi |
number or null | null |
host | High alarm limit. |
hihi |
number or null | null |
host | High-high alarm limit. |
deadband |
number | 0 |
host | Hysteresis: a level is left only when the value is back past its limit by at least deadband (ALARM-003). |
show_limits |
boolean | false |
host | Draw the alarm limits on the scale. |
alarm_level |
"normal", "lo", "lolo", "hi", "hihi" |
"normal" |
derived | Alarm level of value (ALARM-002, ALARM-003). Derived: computed by the host when it owns the state (_session non-empty), otherwise by the front end, which writes it back (HOST-004). |
raw_min |
number or null | null |
host | Engineering scaling: raw reading at eng_min (UNIT-003). Used by the host API only. |
raw_max |
number or null | null |
host | A number, or null when not set. |
eng_min |
number or null | null |
host | A number, or null when not set. |
eng_max |
number or null | null |
host | A number, or null when not set. |
peak_hold |
boolean | false |
host | Track and show the highest value (NUM-110). |
peak_decay |
number | 0 |
host | Seconds after which the held peak is released at the next value; 0: held until reset. |
peak |
number or null | null |
derived | Held peak, null when none. Derived from the history of value (time dependent): by the host when it owns the state, otherwise by the front end (HOST-004). |
Set by: host, the program (Python, Julia, ...); widget, the user through the widget;
derived, computed from other traits by the host that owns the state, or by the widget.
See the trait contract.