PlProgressBox

A row of small glass plates that light up. The third shape, and the one that is about the material rather than about the quantity.

React

import { PlProgressBox } from 'plass-ui';

<PlProgressBox label="Step 3 of 5" value={3} max={5} count={5} showValue />;

import 'package:plass_ui/plass_ui.dart';

PlProgressBox(label: const Text('Step 3 of 5'), value: 3, max: 5, count: 5, showValue: true);

Props

Prop	Type	Default	Description
value	number | null	null	How far along, between min and max. null is the indeterminate case: something is happening and nobody knows how much of it is left
min	number	0	The bottom of the range
max	number	100	The top of the range
label	ReactNode	—	A name for what is loading. Read out with the value by a screen reader
showValue	boolean	false	Shows the value as text beside the shape. A percentage of the range unless format says otherwise
format	Intl.NumberFormatOptions	—	How to format the value when it is shown — Intl.NumberFormat options, so bytes and currencies work as well as plain numbers
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Size of one plate
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. It becomes the gradient of the filled part
count	number	4	How many plates the row is made of. Set it to the number of steps when the thing being waited on genuinely has steps

Prop	Type	Default	Description
value	double?	null	How far along, between min and max. null is the indeterminate case: something is happening and nobody knows how much of it is left
min	double	0	The bottom of the range
max	double	100	The top of the range
count	int	4	How many plates the row is made of. Set it to the number of steps when the thing being waited on genuinely has steps
label	Widget?	—	A name for what is loading. Read out with the value by a screen reader
showValue	bool	false	Shows the value as text beside the shape. A percentage of the range unless format says otherwise
formatValue	String Function(double value)?	—	How to write the value, as a function rather than React's options object: there is no Intl.NumberFormat in the framework, and pulling package:intl in to provide one would be a dependency decision made on the consumer's behalf
sizeshared	PlassSize	PlassSize.md	Size of one plate
colorshared	PlassColor	PlassColor.primary	Semantic colour role. It becomes the gradient of the filled part

Everything above count is PlProgressLinear's table, unchanged except for what size measures: one plate rather than the thickness of a groove.

Every native <div> attribute passes straight through. color is excluded because it collides with the color in the table above, and children because a row of plates holds nothing.

formatValue is a function where React takes an options object, for the reason PlProgressLinear gives.

When to use it

A bar and a ring both answer how much of it is done. A row of plates answers this is working, in the library's own vocabulary (the same groove, the same corner, the same gradient), which makes it the right one for a loading state inside a Plass surface, where a foreign grey spinner would look borrowed.

It is also the one that reads as steps. Set count to the number of steps the thing being waited on actually has and the row becomes a progress sequence rather than a measurement.

Examples

value and count

The plates fill in order, the leading one partially, so four plates at 30% are one full plate and a fifth of the next, rather than one quarter rounded off. That is why each plate is a groove of its own: without it, four plates could only ever show 0, 25, 50, 75 or 100.

React

import { PlProgressBox } from 'plass-ui';

export default function ProgressBoxCount() {
  return (
    <div className="flex flex-col items-start gap-6">
      <PlProgressBox label="Four plates, 30%" value={30} showValue />
      <PlProgressBox label="Five steps, on the third" value={3} max={5} count={5} showValue />
      <PlProgressBox label="Twelve plates" value={30} count={12} showValue />
    </div>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return const Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      spacing: 24,
      children: <Widget>[
        PlProgressBox(label: Text('Four plates, 30%'), value: 30, showValue: true),
        PlProgressBox(
          label: Text('Five steps, on the third'),
          value: 3,
          max: 5,
          count: 5,
          showValue: true,
        ),
        PlProgressBox(label: Text('Twelve plates'), value: 30, count: 12, showValue: true),
      ],
    );
  }
}

Indeterminate

null, the default, sets the row cycling, each plate held back by its own index. What cycles is the fill's opacity and never its paint: a Plass fill is a gradient, and background-image has no interpolation between a gradient and nothing, so a plate that swapped its background would snap rather than light.

The plates never move. A row of them reads as a surface being written to rather than as something bouncing in the corner of a page somebody is reading.

React

import { PlProgressBox } from 'plass-ui';

export default function ProgressBoxIndeterminate() {
  return (
    <div className="flex flex-col items-start gap-6">
      <PlProgressBox label="Known" value={45} showValue />
      <PlProgressBox label="Unknown" />
    </div>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return const Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      spacing: 24,
      children: <Widget>[
        PlProgressBox(label: Text('Known'), value: 45, showValue: true),
        PlProgressBox(label: Text('Unknown')),
      ],
    );
  }
}

size

The plate's own ladder, which is the tick ladder a PlCheckbox's box and a PlRadio's ring are on. A plate is an indicator beside a label, not a control you can put one inside.

React

import { PlProgressBox } from 'plass-ui';

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function ProgressBoxSizes() {
  return (
    <div className="flex flex-col items-start gap-5">
      {sizes.map((size) => (
        <PlProgressBox key={size} size={size} label={size} value={60} />
      ))}
    </div>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      spacing: 20,
      children: <Widget>[
        for (final PlassSize size in PlassSize.values)
          PlProgressBox(size: size, label: Text(size.name), value: 60),
      ],
    );
  }
}

color

React

import { PlProgressBox } from 'plass-ui';

const colors = ['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const;

export default function ProgressBoxColors() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      {colors.map((color) => (
        <PlProgressBox key={color} color={color} label={color} value={65} />
      ))}
    </div>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 24,
      runSpacing: 16,
      children: <Widget>[
        for (final PlassColor color in PlassColor.values)
          PlProgressBox(color: color, label: Text(color.name), value: 65),
      ],
    );
  }
}

Accessibility

• Base UI renders a role="progressbar" and keeps aria-valuenow, aria-valuemin and aria-valuemax in step with the props. The plates themselves are aria-hidden: they are the drawing.
• An indeterminate row reports no value at all rather than zero, which is what tells a screen reader to announce indeterminate progress.
• aria-valuetext is the same string showValue draws. Without format that is a percentage of the range, not of 100, which matters most here, where a row of five plates usually means max={5}.
• Under prefers-reduced-motion the wave is slowed to where it stops reading as motion rather than stopped: a row of plates holding still says the work has stalled.

• The row is one merged semantics node carrying SemanticsRole.progressBar and its value, so the label and the plates are read together. The plates themselves add nothing: they are the drawing.
• With no value the role is SemanticsRole.loadingSpinner and there is no value at all, which is what tells the platform to announce indeterminate progress.
• The drawn percentage is behind ExcludeSemantics: the same string is already the node's value.
• With MediaQuery.disableAnimations the wave is slowed rather than stopped.

Differences from the React build

React	Flutter	Why
format: Intl.NumberFormatOptions	formatValue: String Function(double)	There is no Intl.NumberFormat in the framework, and pulling package:intl in to provide one would be a dependency decision made on the consumer's behalf.
a fractional count is floored	count is an int	Dart's type says it, so nothing has to round. Anything below one is still one.
the wave is a keyframe on each plate's own delay	one controller the plates read at their own phase	Same wave, and one ticker per row rather than one per plate.
className, style, native attributes	—	There is no class list and no style attribute to pass through.