Skip to content

Gauge

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

Gauge, light theme Gauge, dark theme

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.