Progress ring

Pro

Circular completion for a measured value, beside Progress and ContextMeter's ring: how far through a known total something is ("38 of 50 records checked"). It is a progressbar with its value, its maximum and the words for both. A missing value (or one, or a total, that isn't a finite number, or a total of zero or less) draws the track only and says "Unknown", never an empty ring that reads as none done. There's no spinning state: work of unknown length isn't a ring (use StatusDot), because a ring must track a measure. The ring fills only as far as the work has gone: its ends are square, and its share is rounded down. Past the total the ring is full and its words keep the value as measured.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2 and 4.1.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/progress-ring

Brings in: data, locale, scale, tokens, utils

Usage

TSX · The example above

"use client"

import { ProgressRing } from "@/components/candor/progress-ring"

export default function Example() {
  return (
    <ul className="flex max-w-xs flex-col gap-3 text-sm">
      <li className="flex items-center justify-between gap-4">
        Records checked
        <ProgressRing value={38} max={50} label="Records checked" showValue />
      </li>
      <li className="flex items-center justify-between gap-4">
        Pages read
        <ProgressRing value={null} max={120} label="Pages read" showValue />
      </li>
      <li className="flex items-center justify-between gap-4">
        Migration
        <ProgressRing value={12} max={12} label="Tables migrated" size="lg" showValue />
      </li>
    </ul>
  )
}

<ProgressRing>

Prop	Type	Default	Description
valuerequired	`number \| null`	—	How much is done, measured; `null` when it isn't known. A value that isn't a finite number is unknown too.
max	`number \| undefined`	100	The total: a full ring. Defaults to 100. A total of zero or less, or one that isn't a finite number, makes the ring unknown.
labelrequired	`string`	—	What is in progress, the progressbar's name: "Records checked".
size	`"sm" \| "md" \| "lg" \| undefined`	"md"	16, 24 or 40 pixels across. Defaults to md (24).
showValue	`boolean \| undefined`	false	Writes the share done beside the ring ("76%"), rounded down; past the total, the value and the total ("120 of 100").
format	`ValueFormat \| undefined`	"number"	How the value and the total are written in the words read out: number, percent (0–1), currency or duration. Defaults to number.
className	`string \| undefined`	—	Classes for the root, merged with Candor's.

Strings

The fixed words, in English by default. Change any of them under progressRing in <LocaleProvider strings={{ … }}>; the table is exported as progressRingStrings.

Key	English
valueText	{value} of {max}
unknown	Unknown

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

ValueFormat from @/lib/candor/data: "number" | "percent" | "currency" | "duration"