HudPlate
The words around a dial.
Why a plate
A dial drawn in the ring outside the character is a shape: a ring four-fifths full, a needle two-thirds round. It cannot say 83% or four minutes, and it should not try — text at that size inside an SVG is unreadable. So the character keeps the geometry and the plate carries the words: a title, a figure, a unit, and any supporting lines underneath.
The plate does no rounding or formatting. value is shown as given, so the host decides what precision is honest for the figure.
Placement and level
placement puts the text below, above or to the right of the character. level colours the plate — info, ok, warn, alert — and is meant to be rare: a plate that changes tone on every state flickers through four colours in a single turn.
useHudSpec
Hosts assemble a dial out of whatever they have: a fraction that is still undefined on the first render, a token count that arrives as a string. Handing that straight to hud would either draw a wrong dial or throw. useHudSpec takes the kind and the raw values, runs them through the protocol's isHudSpec check, and returns a spec or null — and null simply means no dial, which is the right thing to draw while data is on its way.
The full set of kinds is HUD_KINDS; the shape of each is the HudSpec union, described on the protocol page.
Accessibility
The plate is a polite role="status" region, so a screen reader hears the figure change without being interrupted by it. The dial itself is decorative and hidden from the accessibility tree.
API
| Prop | Type | Default | Description |
|---|---|---|---|
children | string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<AwaitedReactNode> | null | — | The character. Rendered in the slot the placement leaves for it. |
className | string | — | — |
level | HudLevel | 'info' | — |
lines | readonly string[] | — | Supporting lines under the figure: a caption, an arbiter tip, a log tail. |
placement | HudPlacement | 'bottom' | — |
sizePx | number | 72 | Size of the character slot. The plate sizes its own text from this. |
style | CSSProperties | — | — |
title | string | — | What the figure is. |
unit | string | — | Unit for `value`, set smaller and dimmer beside it. |
value | string | number | — | The figure itself, already formatted — this component does no rounding. |
Next
- AgentHud — character, dial and caption together
- Progress HUD — the body works, the ring counts