PlProgressCircular

A ring that fills. The one to use where there is no room for a bar, inside a table row, beside a field, at the end of a line of text.

React

import { PlProgressCircular } from 'plass-ui';

<PlProgressCircular label="Syncing" value={68} showValue />;

import 'package:plass_ui/plass_ui.dart';

PlProgressCircular(label: const Text('Syncing'), value: 68, 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'	Diameter of the ring. Sits just under the control ladder at every step
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. It becomes the gradient of the filled part

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
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	Diameter of the ring. Sits just under the control ladder at every step
colorshared	PlassColor	PlassColor.primary	Semantic colour role. It becomes the gradient of the filled part

The table is PlProgressLinear's, and only size means something different: on a bar it is thickness, on a ring it is diameter. That is the claim the indicators make, one component in three shapes, and it is why they share a props table rather than three that would drift.

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

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

The arc

An SVG stroke cannot be given a CSS gradient, so the ring builds a <linearGradient> of its own out of the same two stops the bar's fill is made of, at the same 135°.

A stroke takes a Shader rather than a decoration, so the sweep the rest of the package gets from PlassCssGradient is asked for directly. The one place in the library a shader is built by hand.

Either way it is worth the extra work: a flat ring beside a swept bar is two materials for one idea.

The track under it is --plass-track, the same neutral ink the bar's groove is, so a ring and a bar on one screen are cut into the same surface.

The value label

Not inside it. A number in the middle of a dial is the picture everyone has of this component, and it works at two of the five sizes: at xs the ring is fourteen pixels across and there is nowhere for "40%" to go. Beside it, every size reads.

Examples

value

null, the default, is the indeterminate case. The ring then draws a fixed quarter-arc and turns, which is the one place the library moves something on its own, and the exception is the same one the button's spinner already has: an indeterminate indicator that holds still is a decoration.

With a value the ring holds still and the gap closes instead. Both are one dash pattern on one circle.

React

import { PlProgressCircular } from 'plass-ui';

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

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

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

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

size

Diameter, on a ladder that sits just under the control ladder at every step, a md ring is 20px inside a 40px control, so a ring dropped into a button, a field or a table row never makes the row taller than it already was.

React

import { PlProgressCircular } from 'plass-ui';

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

export default function ProgressCircularSizes() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      {sizes.map((size) => (
        <PlProgressCircular key={size} size={size} value={65} label={size} />
      ))}
    </div>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 24,
      runSpacing: 16,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        for (final PlassSize size in PlassSize.values)
          PlProgressCircular(size: size, value: 65, label: Text(size.name)),
      ],
    );
  }
}

color

React

import { PlProgressCircular } from 'plass-ui';

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

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

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

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

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

In a row

The size ladder is what this is for: an xs ring in a table cell is fourteen pixels, and the row is the height it was already going to be.

React

import { PlProgressCircular, PlTable } from 'plass-ui';

interface Upload {
  name: string;
  done: number | null;
}

const rows: Upload[] = [
  { name: 'invoice-2026-03.pdf', done: 100 },
  { name: 'annual-report.key', done: 48 },
  { name: 'raw-footage.mov', done: null }
];

export default function ProgressCircularInline() {
  return (
    <PlTable
      className="w-full max-w-md"
      size="sm"
      columns={[
        { key: 'name', header: 'File' },
        {
          key: 'done',
          header: 'Upload',
          align: 'end',
          render: (row: Upload) => (
            <PlProgressCircular
              size="xs"
              value={row.done}
              label={`Uploading ${row.name}`}
              showValue
            />
          )
        }
      ]}
      rows={rows}
      getRowKey={(row: Upload) => row.name}
    />
  );
}

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

class _Upload {
  const _Upload(this.name, this.done);

  final String name;
  final double? done;
}

const List<_Upload> _uploads = <_Upload>[
  _Upload('invoice-2026-03.pdf', 100),
  _Upload('annual-report.key', 48),
  _Upload('raw-footage.mov', null),
];

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

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 380,
      child: PlTable<_Upload>(
        size: PlassSize.sm,
        rows: _uploads,
        columns: <PlTableColumn<_Upload>>[
          PlTableColumn<_Upload>(
            header: const Text('File'),
            cell: (_Upload row, int index) => Text(row.name),
          ),
          PlTableColumn<_Upload>(
            header: const Text('Upload'),
            align: PlassAlign.end,
            cell: (_Upload row, int index) => PlProgressCircular(
              size: PlassSize.xs,
              value: row.done,
              label: Text(row.name),
              showValue: true,
            ),
          ),
        ],
      ),
    );
  }
}

Accessibility

• Base UI renders a role="progressbar" and keeps aria-valuenow, aria-valuemin and aria-valuemax in step with the props.
• An indeterminate ring reports no value at all rather than zero, which is what tells a screen reader to announce indeterminate progress.
• The <svg> is aria-hidden: it is the drawing, and everything it says is already in the role and the value.
• aria-valuetext is the same string showValue draws. Without format that is a percentage of the range, not of 100.
• Under prefers-reduced-motion the ring is slowed to where it stops reading as motion rather than stopped, for the reason it turns at all.

• The ring is one merged semantics node carrying SemanticsRole.progressBar and its value, so the label and the ring are read together.
• 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 ring 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.
an <svg> with a <linearGradient>	a CustomPainter with a ui.Gradient shader	Same two stops, same 135°; a stroke takes a shader rather than a decoration.
className, style, native attributes	—	There is no class list and no style attribute to pass through.