GaugeChart

One number on a scale that is known in advance, drawn as a dial. It reads from further away than a bar of the same value, which is what suits it to a dashboard tile.

import { GaugeChart } from 'neba';

<GaugeChart label="Memory" caption="Memory" value={82} />;

Props

Prop	Type	Default	Description
value *	number | null	—	The reading. null draws the dial with nothing on it
min	number	0	The bottom of the range
max	number	100	The top of the range
sweep	number	180	How far round the dial goes, in degrees, opened symmetrically about twelve o clock. 180 is a half-dial, 270 the instrument shape, 360 a ring
thickness	number	0.22	How thick the arc is, as a fraction of its radius
thresholds	readonly NebaThreshold[]	—	Where the arc changes colour: the same { from, color } entries a Meter takes, with the same rule
ticks	number | false	false	How many marks are drawn around the dial, ends included. Off by default: a gauge on a dashboard is read as a proportion
showRange	boolean	true	Writes min and max at the two ends of the arc
center	ReactNode	—	What goes in the middle. Left out, it is the value written through format
caption	ReactNode	—	A line under the value: the unit, or what is being measured
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	The family the arc carries before any threshold is reached
height	number | string	—	How tall the drawing is. Defaults to the size ladder
format	Intl.NumberFormatOptions	—	How the numbers are written
label	string	—	The accessible name. Given one, the dial is one role="img"
empty	ReactNode	—	What to draw when there is nothing to draw

Every Box prop passes through, so the dial can be a card of its own. There is no legend and no tooltip: one value has nothing to distinguish and nothing to uncover. The number is written in the middle.

It is a Meter bent into an arc, and deliberately the same component in two shapes: value, min, max and thresholds mean what they mean there, so a reading can move from a bar to a dial without changing what it says.

It is not a PieChart with shape="semi". A pie is parts of a whole and every slice is a category; this is one value against a scale, and the unfilled part of the arc is not a second category: it is the rest of the dial.

Examples

value · min · max

value of null draws the dial with nothing on it and a dash in the middle.

thresholds

Where the arc changes colour. The last entry the value has reached wins; below all of them color stands.

import { useState } from 'react';
import { GaugeChart, Slider } from 'neba';

const thresholds = [
  { from: 70, color: 'warning' },
  { from: 90, color: 'danger' }
] as const;

export default function GaugeChartThresholds() {
  const [used, setUsed] = useState(45);

  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <GaugeChart
        variant="outline"
        label="Disk used"
        caption="Disk used"
        value={used}
        thresholds={thresholds}
      />
      <Slider
        aria-label="Disk used"
        value={used}
        onValueChange={(value) => setUsed(value as number)}
      />
    </div>
  );
}

sweep

How far round the dial goes, opened symmetrically about twelve o'clock. 180 is the half-dial a tile wants, 270 is the instrument shape, 360 is a ring. The drawing is sized against the box for the sweep it was given, so a half-dial does not leave an empty half above it.

import { GaugeChart } from 'neba';

const sweeps = [180, 240, 300, 360] as const;

export default function GaugeChartSweep() {
  return (
    <div className="grid w-full max-w-3xl grid-cols-2 gap-4 sm:grid-cols-4">
      {sweeps.map((sweep) => (
        <GaugeChart
          key={sweep}
          variant="outline"
          size="sm"
          label={`${sweep} degrees`}
          caption={`${sweep}°`}
          value={64}
          sweep={sweep}
        />
      ))}
    </div>
  );
}

ticks · thickness · showRange

ticks draws marks around the dial, ends included; it is off by default, because a gauge on a dashboard is read as a proportion and ticks are for an instrument somebody takes a number off. thickness is the arc's weight as a fraction of its radius, and showRange writes min and max at the two ends.

import { GaugeChart } from 'neba';

export default function GaugeChartTicks() {
  return (
    <div className="grid w-full max-w-lg grid-cols-1 gap-4 sm:grid-cols-2">
      <GaugeChart
        variant="outline"
        label="Without marks"
        caption="no ticks"
        value={7.4}
        min={0}
        max={12}
        sweep={270}
        format={{ maximumFractionDigits: 1 }}
      />
      <GaugeChart
        variant="outline"
        label="With marks"
        caption="ticks = 7"
        value={7.4}
        min={0}
        max={12}
        sweep={270}
        ticks={7}
        thickness={0.14}
        format={{ maximumFractionDigits: 1 }}
      />
    </div>
  );
}

center · caption

The value in the middle is real text: selectable, findable, and in the accessibility tree. center replaces it, for the dial whose reading is a word; caption is a line under it for the unit.

Accessibility

• Given a label, the dial is one role="img" named with the reading and the top of its range. Without one it is a plain box, and the number in the middle is read as the text it already is.
• Colour is never the only carrier: a reading that has crossed a threshold has also filled more of the arc, and the number is written out.