ProgressCircular

Shows progress as a ring. Use it in tight space, where there is no room for a horizontal 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
thickness	number	—	The ring's stroke in pixels, when the step's own is not the one you want. size still sets the diameter, and the stroke is held inside the ring

Native <div> attributes pass through to the root. Only color and children are excluded, since the table above spells them differently.

value defaults to null, and the ring spins while indeterminate. min, max and format behave exactly as they do on ProgressLinear.

Examples

size

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>
  );
}

thickness

size is the ring's diameter; thickness is its stroke in pixels, for a dial a screen is actually about. The stroke is held inside the ring — past half the radius there would be no hole left in the middle of it.

<ProgressCircular value={62} size="xl" thickness={6} />

Inside a control

The ring sits one step under the control height at every size (an 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.

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>
  );
}

showValue and label

The value sits beside the ring rather than inside it: at xs the ring is fourteen pixels across and a number would not fit. showValue and label line up in a row with it.

Accessibility

• The SVG drawing is aria-hidden; the value reaches a screen reader through role="progressbar" on the element around it.
• label becomes the accessible name.