UnflowUI
Components

Progress

A determinate progress indicator, linear or circular, with an auto-generated percentage label or status icon.

Overview

Progress renders a determinate progress bar — linear or circular — driven by a value/max pair. It auto-generates a percentage label (or, once a status is set, swaps the label for a success/error icon), and exposes slots/slotProps for full control over the label, icon, track, and indicator.

Import

import { Progress } from '@unflowio/ui/components/Progress';

Props

PropTypeDefaultDescription
valuenumber—Required. Current value, relative to max
labelstring—Accessible name for the progressbar, e.g. "Storage used". Required unless aria-label or aria-labelledby is passed
maxnumber100Upper bound value is measured against
type'linear' | 'circular''linear'Renders a circular indicator instead of the default linear bar
status'success' | 'error'—Tints the indicator and swaps the label for a status icon
hideLabelboolean—Hides the auto-generated label/icon
size'xs' | 'sm' | 'md' | number'sm'Preset size token, or a custom size in px. Controls the diameter when type is circular, and the bar height when type is linear
thicknessnumbersize preset's thicknessStroke width in px. Only used when type is circular
roundedIndicatorbooleantrueRounds the indicator's stroke ends. Only used when type is circular
capPercentagenumber—Restricts the track and indicator to a gauge-style arc spanning this percentage (0-100) of the full circle, leaving a gap centered at the bottom so the ring never fully closes. Only used when type is circular

Basic usage

<Progress value={65} label="Storage used" />

Circular

Set type="circular" to render a ring instead of a bar. size controls the diameter and accepts the same preset tokens (xs/sm/md) or a custom pixel value.

<Progress type="circular" value={65} size="md" label="Storage used" />

Status

Setting status tints the indicator and swaps the percentage label for a status icon, on both linear and circular variants.

<Progress value={100} status="success" label="Upload complete" />
<Progress value={75} status="error" label="Upload failed" />
<Progress type="circular" value={100} status="success" size="md" label="Upload complete" />
<Progress type="circular" value={75} status="error" size="md" label="Upload failed" />

Capped gauge

capPercentage restricts a circular indicator to a gauge-style arc, leaving a gap at the bottom so the ring never fully closes — even once value reaches max.

<Progress type="circular" value={75} size="md" capPercentage={80} label="Seats used" />

Customization (slots & slotProps)

SlotTypeDescription
label(percentage: number, status: ProgressStatus | undefined) => ReactNodeOverrides the auto-generated percentage label
icon(status: ProgressStatus) => ReactNodeOverrides the auto-generated status icon shown once status is set
Slot PropPropsDescription
trackBaseHTMLProps<HTMLDivElement>The background track element
indicatorBaseHTMLProps<HTMLDivElement>The filled indicator element
labelBaseHTMLProps<HTMLParagraphElement>The label element

Accessibility

  • The track (or the circular <svg>) carries role="progressbar" with aria-valuenow, aria-valuemin={0}, aria-valuemax (mirroring max) and aria-valuetext (the rounded percentage).
  • Every progressbar needs a name. label, aria-label and aria-labelledby all land on the progressbar element, not the container; a console warning fires in development when none is set.
  • The default percentage label is aria-hidden, because it repeats aria-valuetext. A custom slots.label or a status label stays exposed. Hiding the label via hideLabel doesn't remove any accessible information.