ProgressCircular

A ring that fills, for where there is no room for a bar.

import { ProgressCircular } from 'neba';

<ProgressCircular value={72} showValue label="Indexing" />
<ProgressCircular />

Props

Prop	Type	Default	Description
value	number | null	null	How far along, between min and max. null — the default — is indeterminate: an indicator that has not been told a value should say so rather than draw an empty bar
min	number	0	The bottom of the range
max	number	100	The top of the range
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Diameter of the ring. It lands just under the control ladder at every step, so dropping one into a button or a field never makes the row taller
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role
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. Percentage of the range unless format says otherwise
format	Intl.NumberFormatOptions	—	How to write the value. Without it the value is a percentage of min…max, the only formatting that holds for a range nobody described

Examples

Sizes

import { ProgressCircular, type NebaSize } from 'neba';

const SIZES: NebaSize[] = ['xs', 'sm', 'md', 'lg', 'xl'];

export default function ProgressCircularSizes() {
  return (
    <div className="flex flex-wrap items-center gap-5">
      {SIZES.map((size) => (
        <ProgressCircular key={size} size={size} value={60} showValue />
      ))}
    </div>
  );
}

Inside a control

The ring lands just under the control ladder at every step — a md ring is 20px inside a 32px control — so dropping one into a button, a field or a table row never makes the row taller than it already was.

import { Button, Chip, ProgressCircular, TextField } from 'neba';

/**
 * The ring lands just under the control height at every step, so it drops into
 * a row of controls without making the row taller than it was.
 */
export default function ProgressCircularInline() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <TextField size="sm" placeholder="Search" endIcon={<ProgressCircular size="xs" />} />
      <Chip
        size="sm"
        variant="text"
        color="info"
        startIcon={<ProgressCircular size="xs" color="info" />}
      >
        Building
      </Chip>
      <Button size="sm" variant="outline" startIcon={<ProgressCircular size="xs" />}>
        Syncing
      </Button>
    </div>
  );
}

The number goes beside it

A percentage in the middle of a dial is the picture everyone has of this component, and it only works at two of the five sizes: at xs the ring is fourteen pixels across and there is nowhere for "40%" to go. Beside the ring, every size reads — so showValue and label sit in a row with it.

The one rotation in the library

The house style is against transforms on a control because scaling or moving one resamples its label. A ring has no label inside it: what turns is a glyph, which is the same allowance the Select chevron takes.

The arc's starting point is an SVG geometry attribute rather than a CSS transform. Without it a determinate ring would fill from three o'clock, which is not what anyone means by "72%".

Accessibility

The drawing is aria-hidden; the value reaches a screen reader through Base UI's role="progressbar" on the element around it, exactly as it does on the bar. label becomes the accessible name.