Skip to the page
TACTILE UI

Kit part · Charts

Needle gauge

A moving-coil panel meter: a printed scale under glass, a thin needle that swings past the mark and settles, a lamp for the bands and a small LCD for the exact reading.

Element
<tui-gauge>
Needs
kit.css + kit.mjs
Rules
gauge.rules.md · 5
Finishes
Aluminium · Graphite · Porcelain · Black
Volumes
Tactile · Quiet
On this page
  1. Variants
  2. Every state, at once
  3. API
  4. Markup
  5. Accessibility
  6. How it’s built
  7. Rules
  8. Related parts
01

Variants

Round · 270°
Arc · wide face, pivot low
Low is bad · alarm under warn
No bands · no readout
02

Every state, at once

Both finishes, side by side. Hover, pressed and focus are forced with .is-hover, .is-down and .is-focus; checked and disabled are real.

Aluminium

PartIn rangeWarning bandAlarm bandOff the scaleNo reading
Round
Arc

Graphite

PartIn rangeWarning bandAlarm bandOff the scaleNo reading
Round
Arc
03

API

NameKindValuesWhat it does
<tui-gauge>elementbuilds its own insideThe meter: bezel, printed face, lamp and name, LCD, zero screw, needle and shadow, pivot cap, glass.
valueattribute · propertynumberThe reading. Setting it swings the needle; past either end it rests on the stop and says so.
min · maxattribute0 · 100The scale’s ends.
labelattributerequiredPrinted on the face beside the lamp, and the meter’s accessible name: “GPU 0”.
unit · unit-textattribute"°C" · "degrees Celsius"Printed large above the pivot and on the LCD; the spoken form for aria-valuetext.
warn · alarmattributenumbers in the scale’s unitsBands from the warning line (hatched) and the alarm line (solid) to the end. Alarm under warn means low is bad.
zonesattribute"from..to warn|alarm, …"Any bands, e.g. both sides of 50 Hz. Overrides warn and alarm.
majorattributeautoThe step between figures. Auto picks 1 · 2 · 2.5 · 5, and prints every other figure when they would crowd.
decimalsattributeautoDecimals on the LCD and in the words.
faceattribute"round" · "arc"A 270° dial, or a 92° arc on a wide face with the pivot low.
readoutattribute"off"Leave the LCD out: the needle and the words only.
--sizeCSS property200px round · 260px arcThe meter’s width; it never grows past its container.
--tui-gauge-sx · --tui-gauge-syCSS property0.8% · 1.4%How far the needle’s shadow falls, down and right.
.needlepropertynumber, read onlyWhere the needle points right now, in the scale’s units; it lags the value while it swings.
data-zone · data-stateattribute"warn" · "alarm" · "none" · "running" · "asleep"Written by the part: the band the value is in, and whether the needle is moving.
KeyboardkeyboardnoneNothing in it takes focus: a meter is read, not operated. Its value is in the accessibility tree.
04

Markup

<tui-gauge label="GPU 0" unit="°C" unit-text="degrees Celsius"
    min="20" max="100" warn="80" alarm="90" value="64"></tui-gauge>

<!-- Grid frequency: an arc face, bands on both sides of 50 Hz -->
<tui-gauge face="arc" label="Grid · L1" unit="Hz" unit-text="hertz"
    min="49.8" max="50.2" value="49.97"
    zones="49.8..49.85 alarm, 49.85..49.9 warn, 50.1..50.15 warn, 50.15..50.2 alarm"></tui-gauge>
import '/kit/kit.mjs';   // defines <tui-gauge>

const gpu = document.querySelector('tui-gauge[label="GPU 0"]');
const source = new EventSource('/telemetry/gpu0');
source.onmessage = (e) => { gpu.value = JSON.parse(e.data).celsius; };   // swings to it

gpu.value;    // the reading: 71.5
gpu.needle;   // where the needle is right now, while it swings

Needs kit.css and kit.mjs. How to install the kit.

05

Accessibility

  • The element is a role="meter" named by its label, with aria-valuemin, aria-valuemax, aria-valuenow and an aria-valuetext that carries the unit and the band: “84 degrees Celsius, in the warning band, 80 to 90”.
  • It takes no focus and needs none: there is nothing to operate. The face, the needle and the LCD are its picture and are hidden from assistive technology.
  • Bands are printed in ink (hatched for warning, solid for alarm) and the lamp by the name lights amber or red: position, print and light, never colour alone.
  • Reduced motion: the needle jumps to the reading; the LCD, the lamp and the words are exactly the same.
06

How it’s built

Plain DOM and SVG, no canvas. The face is printed once as SVG from the scale (ticks, figures, the unit, hatched and solid bands) and reprinted only when the scale changes. The needle and its counterweight are one small SVG turned by a CSS rotate() about the pivot; its shadow is the same silhouette, blurred, translated down and right after the turn, so it falls away from the lamp at every angle. The pivot cap, the bezel’s bow-tie highlight and the glass’s glare are fixed layers above and below: nothing lit turns. The needle is θ̈ = ω₀²(target − θ) − 2ζω₀θ̇ at 1.35 Hz and ζ 0.62 (it passes the mark by about 8% and settles in about a second) with soft stops just past both ends. The loop sub-steps at 1/240 s, clamps a frame to 1/30 s, sleeps when the needle settles, and pauses off screen and in a hidden tab.

07

Rules

gauge.rules.mdIn the brain

A needle shows where a value sits and how fast it moves; the LCD in the face gives the figure. Bands are printed in ink and a lamp lights beside the name.

5 rules in this file, with the foundations they rest on and the anti-patterns that break them. Full rules ship in the brain with the Pass.

08

Knob

A rotary control for continuous or stepped values where space is square. Its knurl and pointer turn; its light does not.

Ladder

An LED ladder for levels and load: green, then amber, then red, the way a recording level has always been read.

02:52min

LCD

A value that changes, on grey-green liquid crystal, with a ghost of the unlit segments behind it: clocks, battery, counters.

Docs
Finish
Volume