Skip to content

Meter

A value against a limit, as a bar always paired with its number in text.

<div class="cap-meter" data-cap="meter" id="sample-low">
  <span class="cap-meter-label" id="sample-low-l">R2 storage</span>
  <span class="cap-meter-value">1.2 of 10 GB</span>
  <span class="cap-meter-bar" role="meter" aria-labelledby="sample-low-l" aria-valuemin="0" aria-valuemax="10" aria-valuenow="1.2" aria-valuetext="1.2 of 10 gigabytes stored"><span class="cap-meter-fill"></span></span>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/meter.css";
import { enhance } from "capsomer/behavior/meter";

enhance();

Usage

<div class="cap-meter" data-cap="meter" data-tone="warn" data-size="md">
  <span class="cap-meter-label" id="req-l">Worker requests</span>
  <span class="cap-status" data-tone="warn">[warning glyph]Near the limit</span>
  <span class="cap-meter-value">78,000 of 100,000</span>
  <span class="cap-meter-bar" role="meter" aria-labelledby="req-l"
        aria-valuemin="0" aria-valuemax="100000" aria-valuenow="78000"
        aria-valuetext="78,000 of 100,000 requests today. Warning: near the limit."
        data-threshold="75000" data-projected="91000"><span class="cap-meter-fill"></span></span>
  <span class="cap-meter-note">The tick marks the 75,000 warning line. Resets at midnight UTC.</span>
</div>

Examples

Warning

<div class="cap-meter" data-cap="meter" data-tone="warn" id="sample-warn">
  <span class="cap-meter-label" id="sample-warn-l">Worker requests</span>
  <span class="cap-status" data-tone="warn"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M8 1.2 15.4 14H.6zM7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z"/></svg>Near the limit</span>
  <span class="cap-meter-value">78,000 of 100,000</span>
  <span class="cap-meter-bar" role="meter" aria-labelledby="sample-warn-l" aria-valuemin="0" aria-valuemax="100000" aria-valuenow="78000" aria-valuetext="78,000 of 100,000 requests today. Warning: near the limit. Resets at midnight UTC."><span class="cap-meter-fill"></span></span>
  <span class="cap-meter-note">Resets at midnight UTC.</span>
</div>

Critical

<div class="cap-meter" data-cap="meter" data-tone="crit" id="sample-crit">
  <span class="cap-meter-label" id="sample-crit-l">KV writes</span>
  <span class="cap-status" data-tone="crit"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z"/></svg>Almost out</span>
  <span class="cap-meter-value">962 of 1,000</span>
  <span class="cap-meter-bar" role="meter" aria-labelledby="sample-crit-l" aria-valuemin="0" aria-valuemax="1000" aria-valuenow="962" aria-valuetext="962 of 1,000 writes today. Critical: writes stop at 1,000."><span class="cap-meter-fill"></span></span>
  <span class="cap-meter-note">Writes stop at 1,000 until midnight UTC.</span>
</div>

Full

<div class="cap-meter" data-cap="meter" data-tone="crit" id="sample-full">
  <span class="cap-meter-label" id="sample-full-l">D1 rows read</span>
  <span class="cap-status" data-tone="crit"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z"/></svg>Limit reached</span>
  <span class="cap-meter-value">5,000,000 of 5,000,000</span>
  <span class="cap-meter-bar" role="meter" aria-labelledby="sample-full-l" aria-valuemin="0" aria-valuemax="5000000" aria-valuenow="5000000" aria-valuetext="5 million of 5 million rows read today. Limit reached: reads fail until midnight UTC."><span class="cap-meter-fill"></span></span>
  <span class="cap-meter-note">Reads fail until midnight UTC.</span>
</div>

A threshold tick

<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>

Sizes

<div class="cap-meter" data-cap="meter" data-size="sm" id="sample-sm">
  <span class="cap-meter-label" id="sample-sm-l">Small bar</span>
  <span class="cap-meter-value">30 of 100</span>
  <span class="cap-meter-bar" role="meter" aria-labelledby="sample-sm-l" aria-valuemin="0" aria-valuemax="100" aria-valuenow="30" aria-valuetext="30 of 100"><span class="cap-meter-fill"></span></span>
</div>
<div class="cap-meter" data-cap="meter" id="sample-md">
  <span class="cap-meter-label" id="sample-md-l">Default bar</span>
  <span class="cap-meter-value">50 of 100</span>
  <span class="cap-meter-bar" role="meter" aria-labelledby="sample-md-l" aria-valuemin="0" aria-valuemax="100" aria-valuenow="50" aria-valuetext="50 of 100"><span class="cap-meter-fill"></span></span>
</div>
<div class="cap-meter" data-cap="meter" data-size="lg" id="sample-lg">
  <span class="cap-meter-label" id="sample-lg-l">Large bar</span>
  <span class="cap-meter-value">70 of 100</span>
  <span class="cap-meter-bar" role="meter" aria-labelledby="sample-lg-l" aria-valuemin="0" aria-valuemax="100" aria-valuenow="70" aria-valuetext="70 of 100"><span class="cap-meter-fill"></span></span>
</div>

No data

<div class="cap-meter" data-tone="nodata" id="sample-nodata">
  <span class="cap-meter-label">Queue minutes</span>
  <span class="cap-meter-value"><span class="cap-status" data-tone="nodata"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle cx="8" cy="8" r="6.2" fill="none" stroke="currentColor" stroke-width="1.6"/><path d="M5 8h6" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>No data</span></span>
  <span class="cap-meter-bar" aria-hidden="true"><span class="cap-meter-fill"></span></span>
  <span class="cap-meter-note">Cloudflare's analytics have not reported since 09:00.</span>
</div>

Measuring

<div class="cap-meter" data-state="indeterminate" aria-busy="true" id="sample-indeterminate">
  <span class="cap-meter-label">Storage used</span>
  <span class="cap-meter-value"><span class="cap-status" data-tone="nodata"><svg class="cap-status-glyph" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle cx="8" cy="8" r="6.2" fill="none" stroke="currentColor" stroke-width="1.6"/><path d="M5 8h6" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>Measuring</span></span>
  <span class="cap-meter-bar" aria-hidden="true"><span class="cap-meter-fill"></span></span>
  <span class="cap-meter-note">Counting objects in the bucket. This takes a few seconds.</span>
</div>

A native meter, where its plain look is enough

<div>
  <label for="sample-native">Draft length</label> <span class="cap-muted cap-num">1,460 of 2,000 words</span>
  <meter class="cap-meter" id="sample-native" min="0" max="2000" low="1600" high="1900" optimum="1000" value="1460">1,460 of 2,000 words</meter>
</div>

API reference

Meter

PropTypeRequiredDoes
labelReactNodeYes
valuenumber | nullYesnull is no data: the meter shows the no data state and its reason (in note), never a bar at zero.
maxnumberYes
minnumber
valueTextstringYesWhat a screen reader hears, whole: "78,000 of 100,000 requests today. Near the limit."
displayReactNodeThe number shown beside the label. Defaults to "value of max".
toneMeterToneOverrides the tone from the thresholds.
warnAtnumberTone by threshold, as a share of the span: warning from warnAt, critical from critAt. Without either, the tone is the tone prop or none.
critAtnumber
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.
thresholdnumberA threshold tick and a projection, in the same unit as value.
projectednumber
size"sm" | "md" | "lg"
measuringbooleanThe value is being measured now: an indeterminate bar with the reason in note.
noteReactNodeA line under the bar: what happens next, or why there is no data.
classNamestringFor 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"
afterReactNode

Functions

FunctionSignatureDoes
percent(value: number, max?: number, min?: number): numberThe 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): numberThe 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; }): MeterToneThe 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): voidSets one bar's positions from its values.
update(bar: HTMLElement): voidReads a bar's aria-valuenow, aria-valuemin, aria-valuemax, data-projected and data-threshold and draws it.
enhance(root?: ParentNode): () => voidAttaches 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

VariableDefault
--cap-meter-colorvar(--accent)
--cap-meter-hvar(--space-3)
--cap-meter-projected0
--cap-meter-ratio0.4
--cap-meter-threshold0

Parts and data attributes

ClassIs
.cap-meterthe root
.cap-meter-bara part
.cap-meter-filla part
.cap-meter-labela part
.cap-meter-notea part
.cap-meter-valuea part
AttributeValues
data-projectedpresent or absent
data-sizelg sm
data-stateindeterminate
data-thresholdpresent or absent
data-tonecrit info nodata warn

Accessibility

KeyDoes
NoneA 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.