Skip to content

Knob

Rotary control with a pointer (NUM-101).

Knob, light theme Knob, dark theme

Controls, continuous · Widget catalog · API reference · schema knob.schema.json

Example

The traits of the picture above:

ai.Knob(value=35, label="Knob", unit="%")

Traits

Trait Type Default Set by Description
angle_range number 270 host Angle swept by the scale, in degrees.
Common traits (35), shared with other widgets
Trait Type Default Set by Description
mode "control", "indicator" "control" host "control": the user sets the value; "indicator": display only.
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.

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.