<div class="cap-meter" data-cap="meter" id="sample-threshold">
<span class="cap-meter-label" id="sample-threshold-l">Draft length</span>
<span class="cap-meter-value">1,460 of 2,000 words</span>
<span class="cap-meter-bar" role="meter" aria-labelledby="sample-threshold-l" aria-valuemin="0" aria-valuemax="2000" aria-valuenow="1460" aria-valuetext="1,460 of 2,000 words. The target of 1,600 words is marked on the bar." data-threshold="1600"><span class="cap-meter-fill"></span></span>
<span class="cap-meter-note">The tick marks the 1,600-word target.</span>
</div>
A projection
<div class="cap-meter" data-cap="meter" id="sample-projection">
<span class="cap-meter-label" id="sample-projection-l">Worker requests</span>
<span class="cap-meter-value">61,400 of 100,000</span>
<span class="cap-meter-bar" role="meter" aria-labelledby="sample-projection-l" aria-valuemin="0" aria-valuemax="100000" aria-valuenow="61400" aria-valuetext="61,400 of 100,000 requests today, projected 87 percent by the reset" data-projected="86682"><span class="cap-meter-fill"></span></span>
<span class="cap-meter-note">Solid is used; hatched, with its end marked, is where the day ends at the current rate.</span>
</div>
null is no data: the meter shows the no data state and its reason (in note), never a bar at zero.
max
number
Yes
min
number
valueText
string
Yes
What a screen reader hears, whole: "78,000 of 100,000 requests today. Near the limit."
display
ReactNode
The number shown beside the label. Defaults to "value of max".
tone
MeterTone
Overrides the tone from the thresholds.
warnAt
number
Tone by threshold, as a share of the span: warning from warnAt, critical from critAt. Without either, the tone is the tone prop or none.
critAt
number
words
{ warn: string; crit: string }
The word shown with a warn or crit tone, so color is never alone. Shown when the tone comes from warnAt/critAt, or when this is given; with a plain tone prop and no words, the word is the caller's, in note.
threshold
number
A threshold tick and a projection, in the same unit as value.
projected
number
size
"sm" | "md" | "lg"
measuring
boolean
The value is being measured now: an indeterminate bar with the reason in note.
note
ReactNode
A line under the bar: what happens next, or why there is no data.
className
string
For compositions (the usage meter's row): extra class names, the root element, and content after the bar, inside the meter's row.
as
"div" | "li"
after
ReactNode
Functions
Function
Signature
Does
percent
(value: number, max?: number, min?: number): number
The share of a span as a whole percent, 0 to 100: an upload's progress for a meter's value and label.
ratio
(value: number, max: number, min?: number): number
The share of the span, from 0 to 1. A missing, negative or non-finite value is 0.
toneFor
(value: number, max: number, options?: { min?: number | undefined; warnAt?: number | undefined; critAt?: number | undefined; }): MeterTone
The tone a value earns by threshold: warning from warnAt of the span, critical from critAt (both 0 to 1; the defaults are the usage meter's 75% and 90%). The caller still writes the status word beside it: a tone is a word, a shape and a color, never color.
setBar
(bar: HTMLElement, v: BarValues): void
Sets one bar's positions from its values.
update
(bar: HTMLElement): void
Reads a bar's aria-valuenow, aria-valuemin, aria-valuemax, data-projected and data-threshold and draws it.
enhance
(root?: ParentNode): () => void
Attaches to every [data-cap="meter"] under root (or root itself) not yet attached, draws its bar, and redraws it whenever a value changes. Returns a function that detaches.
CSS variables
Variable
Default
--cap-meter-color
var(--accent)
--cap-meter-h
var(--space-3)
--cap-meter-projected
0
--cap-meter-ratio
0.4
--cap-meter-threshold
0
Parts and data attributes
Class
Is
.cap-meter
the root
.cap-meter-bar
a part
.cap-meter-fill
a part
.cap-meter-label
a part
.cap-meter-note
a part
.cap-meter-value
a part
Attribute
Values
data-projected
present or absent
data-size
lgsm
data-state
indeterminate
data-threshold
present or absent
data-tone
critinfonodatawarn
Accessibility
Key
Does
None
A meter is read, not operated. It takes no focus.
The label is --text and the number --muted, 4.5:1 in both themes; the fill is 3:1 against its track in every tone.
Everything shown must be in aria-valuetext or in text beside the bar: the tick, the projection and the tone are never color or position alone.
Reduced motion: the fill does not ease and the measuring segment does not slide.
Forced colors: the bar gains an edge, the fill and the tick are painted in CanvasText and the hatching in CanvasText on Canvas.