PlGaugeChart

One number on a scale that is known in advance, drawn as a dial. A PlMeter bent into an arc, for a tile of its own rather than a row of fields.

React

import { PlGaugeChart } from 'plass-ui';

<PlGaugeChart value={68} caption="of quota" />;

import 'package:plass_ui/plass_ui.dart';

PlGaugeChart(value: 68, caption: Text('of quota'));

value, min, max and thresholds mean exactly what they mean on a meter, so a page can move a reading from a bar to a dial without changing what it says. Reach for the bar in a row of fields and for this one where a dial reads at a glance from across a room and a four-pixel bar does not.

It is not a pie chart 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.

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 scale
max	number	100	And the top of it
sweep	number	180	How far round the dial goes, in degrees, opened symmetrically about twelve
thickness	number	0.22	How thick the arc is, as a fraction of its radius
thresholds	readonly PlassThreshold[]	—	Where the arc changes colour. The meter's rule: the highest band at or below the value wins
ticks	number | false	false	How many marks are drawn around the dial, ends included
showRange	boolean	true	Writes min and max at the two ends. Dropped past 330 degrees whatever it says
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
height	number | string	—	How tall the drawing is
format	Intl.NumberFormatOptions	—	How a value is written
label	string	—	What the dial is called. Without one it stays a plain box
empty	ReactNode	—	What is drawn when there is nothing to draw
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	The family the arc takes where no threshold applies
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Type scale and dial height

Prop	Type	Default	Description
value *	double?	—	The reading. null draws the dial with nothing on it
min	double	0	The bottom of the scale
max	double	100	And the top of it
sweep	double	180	How far round the dial goes, in degrees, opened symmetrically about twelve
thickness	double	0.22	How thick the arc is, as a fraction of its radius
thresholds	List<PlassThreshold>?	—	Where the arc changes colour. The meter's rule: the highest band at or below the value wins
ticks	int?	false	How many marks are drawn around the dial. null is off, where React writes false
showRange	bool	true	Writes min and max at the two ends. Dropped past 330 degrees whatever it says
center	Widget?	—	What goes in the middle. Left out, it is the value written through format
caption	Widget?	—	A line under the value: the unit, or what is being measured
height	double?	—	How tall the drawing is
format	String Function(double)?	—	How a value is written
semanticLabel	String?	—	What the dial is called. Without one it stays a plain box
empty	Widget?	—	What is drawn when there is nothing to draw
colorshared	PlassColor	PlassColor.primary	The family the arc takes where no threshold applies
sizeshared	PlassSize	PlassSize.md	Type scale and dial height

A null value draws the dial with nothing on it, which is the honest picture of an instrument that has not been told anything. There is no legend and no tooltip: one number needs neither.

What the shared props mean across the library is in prop conventions.

Examples

sweep

React

import { PlGaugeChart } from 'plass-ui';

export default function GaugeChartSweep() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      {[180, 270, 360].map((sweep) => (
        <PlGaugeChart
          key={sweep}
          label={`Load at ${sweep} degrees`}
          value={62}
          sweep={sweep}
          height={160}
          caption={`${sweep}°`}
        />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class GaugeChartSweep extends StatelessWidget {
  const GaugeChartSweep({super.key});

  @override
  Widget build(BuildContext context) {
    return Row(
      children: <Widget>[
        for (final double sweep in <double>[180, 270, 360])
          Expanded(
            child: Padding(
              padding: const EdgeInsets.symmetric(horizontal: 6),
              child: PlGaugeChart(
                value: 62,
                sweep: sweep,
                height: 160,
                caption: Text('${sweep.toInt()}°'),
                semanticLabel: 'Load at ${sweep.toInt()} degrees',
              ),
            ),
          ),
      ],
    );
  }
}

Degrees, opened symmetrically about twelve o'clock. 180 is the half-dial for a dashboard tile, 270 is the instrument shape, 360 is a ring.

The dial is sized against the box rather than assuming a circle, because how far it reaches below its centre depends on the sweep: a half-dial stops level with the centre and a 270° one drops most of a radius past it. That is what keeps a wide, short card from drawing a thin band with an empty half above it.

thresholds

React

import { PlGaugeChart } from 'plass-ui';

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

export default function GaugeChartThresholds() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      {[42, 78, 96].map((value) => (
        <PlGaugeChart
          key={value}
          label={`Disk at ${value} percent`}
          value={value}
          thresholds={bands}
          height={160}
          caption="disk"
        />
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

const List<PlassThreshold> _bands = <PlassThreshold>[
  PlassThreshold(from: 70, color: PlassColor.warning),
  PlassThreshold(from: 90, color: PlassColor.danger),
];

class GaugeChartThresholds extends StatelessWidget {
  const GaugeChartThresholds({super.key});

  @override
  Widget build(BuildContext context) {
    return Row(
      children: <Widget>[
        for (final double value in <double>[42, 78, 96])
          Expanded(
            child: Padding(
              padding: const EdgeInsets.symmetric(horizontal: 6),
              child: PlGaugeChart(
                value: value,
                thresholds: _bands,
                height: 160,
                caption: const Text('disk'),
                semanticLabel: 'Disk at ${value.toInt()} percent',
              ),
            ),
          ),
      ],
    );
  }
}

The highest band at or below the value wins, and color is what the arc is made of below all of them. Order in the list does not matter (the bands are read, not walked), which is the same rule and the same code a PlMeter uses.

A band is a second way of saying the number, never the only one. The reading is written in the middle whatever colour the arc has taken.

ticks and showRange

React

import { PlGaugeChart } from 'plass-ui';

export default function GaugeChartTicks() {
  return (
    <PlGaugeChart
      className="w-full max-w-xs"
      label="Line pressure"
      value={4.2}
      min={0}
      max={6}
      sweep={270}
      ticks={7}
      caption="bar"
      format={{ maximumFractionDigits: 1 }}
    />
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class GaugeChartTicks extends StatelessWidget {
  const GaugeChartTicks({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      height: 220,
      child: PlGaugeChart(
        value: 4.2,
        max: 6,
        sweep: 270,
        ticks: 7,
        caption: const Text('bar'),
        semanticLabel: 'Line pressure',
        format: (double value) => value.toStringAsFixed(1),
      ),
    );
  }
}

Ticks are off by default. A gauge on a dashboard is read as a proportion, and marks around the rim are for an instrument somebody takes a number off.

showRange writes min and max at the two ends, and is dropped past 330° whatever it says: by then the two ends have come within a label's width of each other, and 0 and 100 set on top of each other is a smudge rather than a scale.

center and caption

center replaces the number in the hole, and caption hangs a line under it. Replacing the reading is for adding to it rather than for taking it away. The number is what the dial is for.

The reading is real text, not a label painted into the drawing, so it can be selected, found by the browser's own search and read without the chart having to describe itself. Its size is solved against the room the hole actually leaves rather than fixed, because 38 and 10,000% are the same prop.

Accessibility

• With a label the dial is one named image saying one thing: "Storage used: 1.36 / 2". That saves a reader hearing the two end labels as loose numbers.
• Without one it stays a plain box, and the reading in the middle is read as the text it already is.
• The value is never carried by colour alone. A threshold changes the family; the number in the middle says the same thing in words.
• The arc sweeps to a new reading rather than jumping to it, and the sweep is a length rather than a transform. The numbers written across the dial are never resampled.