`<bmx-gauge>`

One value on a scale: a dial (radial, semi, ring), a bar (linear, vertical) or a bullet graph (bullet). Bands colour parts of the scale (green, amber, red, or any colours) and name them; a target marks where the value should be; compare shows the change from an earlier value. The value moves to each new value it is given (not with reduced motion).

27 properties · 2 events · 1 methods · 3 parts

Example

Bars and a bullet graph

A dial the reader sets

With interactive it is a slider: drag the dial, or use the arrow keys, Page Up and Page Down, Home and End. With a name it is a form field.

New CPU reading

Show markup

<div class="row" style="gap: 1.5rem; flex-wrap: wrap; align-items: flex-start">
  <bmx-gauge id="ex-g-cpu" value="72" unit="%" ranges="0-60:success:Normal,60-85:warning:Busy,85-:danger:Overloaded" target="80" label="CPU" compare="64" compare-label="vs last hour" style="--bmx-gauge-size: 14rem"></bmx-gauge>
  <bmx-gauge type="semi" indicator="needle" value="3420" max="6000" unit=" rpm" ranges="0-4500:success,4500-5500:warning,5500-:danger" label="Engine speed" style="--bmx-gauge-size: 14rem"></bmx-gauge>
  <bmx-gauge type="ring" value="0.68" max="1" format="percent" ticks="false" label="Quarterly target" style="--bmx-gauge-size: 10rem"></bmx-gauge>
  <bmx-gauge type="vertical" value="21.5" min="-10" max="40" unit=" °C" ranges="-10-5:info:Cold,5-25:success:Comfortable,25-:danger:Hot" label="Server room" format="decimal:1"></bmx-gauge>
</div>

<h3>Bars and a bullet graph</h3>

<div style="display: grid; gap: 1rem; max-inline-size: 36rem">
  <bmx-gauge type="linear" value="640" max="1000" unit=" GB" ranges="0-700:success,700-900:warning,900-:danger" label="Disk used" compare="590" compare-label="last week"></bmx-gauge>
  <bmx-gauge type="bullet" value="270" max="400" target="300" format="currency:GBP" ranges="0-200:neutral:Poor,200-300:neutral:Fair,300-:neutral:Good" label="Revenue (thousands)"></bmx-gauge>
</div>

<h3>A dial the reader sets</h3>

<p class="note">With <code>interactive</code> it is a slider: drag the dial, or use the arrow keys, Page Up and Page Down, Home and End. With a <code>name</code> it is a form field.</p>
<div class="row" style="gap: 1.5rem; flex-wrap: wrap; align-items: center">
  <bmx-gauge id="ex-g-set" interactive type="radial" value="20" min="10" max="30" step="0.5" unit=" °C" format="decimal:1" label="Thermostat" style="--bmx-gauge-size: 13rem"></bmx-gauge>
  <bmx-gauge id="ex-g-vol" interactive type="linear" value="35" unit="%" label="Volume" style="inline-size: 16rem"></bmx-gauge>
</div>
<p class="note" id="ex-g-out" role="status"></p>

<div class="row" style="margin-block-start: 0.75rem; gap: 0.5rem">
  <bmx-button variant="outline" tone="neutral" id="ex-g-random">New CPU reading</bmx-button>
</div>

<script type="module">
  await customElements.whenDefined('bmx-gauge');
  const cpu = document.getElementById('ex-g-cpu');
  const out = document.getElementById('ex-g-out');
  document.getElementById('ex-g-random').addEventListener('click', () => {
    cpu.compare = cpu.value;
    cpu.value = Math.round(20 + Math.random() * 78);
  });
  for (const id of ['ex-g-set', 'ex-g-vol']) {
    document.getElementById(id).addEventListener('bmxGaugeChange', e => {
      out.textContent = `${e.target.label} set to ${e.detail.value}${e.target.unit}.`;
    });
  }
</script>

A screen reader hears it as a meter: "CPU, 72%, Busy, target 80%". With interactive it is a dial the reader sets - drag it, or use the arrow keys, Page Up and Page Down, Home and End - and a form field with a name.

Properties

Property	Attribute	Type	Default	Description
`animated`	`animated`	`boolean`	`true`	The value moves to each new value rather than jumping (never with reduced motion).
`colorByRange`	`color-by-range`	`boolean`	`true`	The value's bar takes the colour of the band it is in.
`compare`	`compare`	`number`	—	An earlier value: the change from it is shown and read.
`compareLabel`	`compare-label`	`string`	—	What the earlier value was ("last month"), shown after the change.
`disabled`	`disabled`	`boolean`	`false`	Turns an interactive gauge off.
`endAngle`	`end-angle`	`number`	—	Where a dial ends, in degrees.
`format`	`format`	`BmxChartNumberFormat \| string`	—	How values are written: `currency:EUR`, `decimal:1`, `compact`, `percent` (0.25 is 25%), or the object.
`indicator`	`indicator`	`'bar' \| 'needle'`	`'bar'`	How the value is shown on a dial: `bar` (default) or `needle`.
`interactive`	`interactive`	`boolean`	`false`	The reader sets the value: by dragging, or with the keyboard.
`label`	`label`	`string`	—	What the gauge measures: the caption and its accessible name.
`locale`	`locale`	`string`	—	A BCP 47 locale for numbers. Default: the page's `lang`.
`majorTicks`	`major-ticks`	`number`	`5`	About how many numbered ticks.
`max`	`max`	`number`	`100`	The top of the scale.
`min`	`min`	`number`	`0`	The bottom of the scale.
`minorTicks`	`minor-ticks`	`number`	`4`	Small ticks between numbered ones.
`name`	`name`	`string`	—	With a name, an interactive gauge's value goes into an enclosing `<form>`.
`ranges`	`ranges`	`BmxGaugeRange[] \| string`	—	Bands of the scale: `0-60:success, 60-85:warning:Busy, 85-:danger`, or `[{ from, to, color, label }]`.
`showValue`	`show-value`	`boolean`	`true`	Show the value written out.
`startAngle`	`start-angle`	`number`	—	Where a dial starts, in degrees from twelve o'clock (clockwise). The type's own, by default.
`step`	`step`	`number`	`1`	The steps an interactive value moves in.
`strings`	`strings`	`Partial<BmxGaugeStrings> \| string`	—	Words it is read with, to translate: any of `BmxGaugeStrings`. JSON in markup.
`target`	`target`	`number`	—	Where the value should be: a mark on the scale.
`thickness`	`thickness`	`number`	`0.16`	How thick a dial's arc is, as a share of its radius (0.04 to 0.5).
`ticks`	`ticks`	`boolean`	`true`	Show the scale's ticks and their numbers.
`type`	`type`	`BmxGaugeType`	`'radial'`	`radial` (270 degrees, default), `semi`, `ring`, `linear`, `vertical` or `bullet`.
`unit`	`unit`	`string`	—	Written after every number: `%` on a 0-100 scale, `°C`, `rpm`.
`value`	`value`	`number`	`0`	The value. Set by the reader when `interactive`.

Events

Event	Detail	Description
`bmxGaugeChange`	`BmxGaugeChangeDetail`	The reader set a value.
`bmxGaugeInput`	`BmxGaugeChangeDetail`	The reader is moving the value.

Methods

Method	Signature	Description
`setValue`	`setValue(value: number) => Promise<void>`	Sets the value as the reader would, with the events.

CSS shadow parts

Part	Description
`gauge`	the drawing.
`label`	the caption.
`value`	the value written out.

CSS custom properties

Property	Description
`--bmx-gauge-bar-height`	How tall a linear or bullet gauge's drawing is. Default 3.25rem.
`--bmx-gauge-bullet-color`	A bullet graph's bar.
`--bmx-gauge-color`	The value's bar and needle, outside any band.
`--bmx-gauge-size`	How wide a dial is. Default: the width it is given, up to 16rem.
`--bmx-gauge-target`	The target mark.
`--bmx-gauge-text`	The value and the numbers.
`--bmx-gauge-track`	The scale behind the value.
`--bmx-gauge-vertical-height`	How tall a vertical gauge is. Default 14rem.