Skip to content
Tier

Stage ring

Pro

A small ring of equal segments, one per stage, for a list or a header where a full Stepper is too busy. It takes the same steps and current as Stepper, so one array of stages can drive both, and draws each in its state: done, current, waiting on the person, failed or not started. It is a summary of states, not progress: it shows no share and fills nothing in.

It never relies on colour alone. A line of text beside it names the current stage and its state ("Build · Current step"), or the app's own words through status, and counts any other stages that failed or need the person ("· 1 failed · 1 needs you"). An app that already prints that text beside the ring passes its id as statusId instead, and the ring draws no line; that text should count those stages too. Each state also has its own stroke (thin, solid, thicker, dotted or broken); in forced colours the strokes are drawn in the system's colours and their shapes carry the states. At small sizes the dotted and broken strokes are hard to tell apart, so the text is what carries the state. The ring's accessible name lists every stage and its state, its description gives the stages' details, and a tooltip on hover and keyboard focus lists them with their details.

Sizes are in pixels: 24 by default. It stays legible down to 20 pixels with up to eight stages; below that, or with more stages, the segments run together.

Markdown

Preview

Loading the 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/stage-ring

Brings in: bidi, locale, stepper, tokens, tooltip, utils

Usage

TSX · The example above
"use client"

import { StageRing } from "@/components/candor/stage-ring"
import type { StepperStep } from "@/components/candor/ui/stepper"

// The same stages a Stepper takes. Each one's state is the app's data; the ring never decides that a stage is done.
const stages = (done: number, last: Partial<StepperStep> = {}): StepperStep[] =>
  ["Talk", "Plan", "Build", "Prove", "Hand-over", "Your review", "Accepted"].map((title, i) => ({
    id: title,
    title,
    done: i < done,
    ...(i === done ? last : {}),
  }))

export default function Example() {
  return (
    <ul className="flex max-w-sm flex-col gap-3 text-sm">
      <li className="flex items-center justify-between gap-4">
        Billing export
        <StageRing stages={stages(2)} current="Build" label="Delivery" size={30} status="Build · part 6 of 9" />
      </li>
      <li className="flex items-center justify-between gap-4">
        Supplier portal
        <StageRing stages={stages(4, { waiting: "Your sign-off" })} label="Delivery" size={30} />
      </li>
      <li className="flex items-center justify-between gap-4">
        Onboarding flow
        <span className="flex items-center gap-1.5">
          <StageRing stages={stages(3, { failed: true })} label="Delivery" size={22} statusId="onboarding-line" />
          <span id="onboarding-line" className="text-xs text-muted-foreground">
            Prove · 2 checks failed
          </span>
        </span>
      </li>
      <li>
        {/* tooltip={false}: inside a link (a card that is one), the ring is an image with no button, named with its stages. */}
        <a href="#data-sync" className="flex w-full items-center justify-between gap-4 underline-offset-2 hover:underline">
          Data sync
          <StageRing stages={stages(1)} label="Delivery" size={30} tooltip={false} />
        </a>
      </li>
    </ul>
  )
}

<StageRing>

PropTypeDefaultDescription
stagesrequiredStepperStep[]—The stages in order, in `Stepper`'s shape: each one's `done`, `failed` and `waiting` come from the app.
currentstring | undefined—The id of the stage the work is at, as for `Stepper`. Left out, the line names the first stage not yet done.
labelstring | undefined—What the stages are of, the start of the ring's accessible name ("Delivery"). Defaults to "Stages".
sizenumber | undefinedDEFAULT_SIZEHow wide the ring is, in pixels. Defaults to 24; it stays legible down to 20 with up to eight stages.
statusReact.ReactNode | undefined—The line beside the ring, in the app's words ("Build · part 6 of 9"). Left out, the line names the current stage and its state. Either way, other stages that failed or need the person are counted after it.
statusIdstring | undefined—The id of the app's own text beside the ring that names the current stage and its state. Given, the ring draws no line of its own and is described by that text instead.
tooltipboolean | undefinedtrue`true` (the default): the ring is a button that shows the stages in a tooltip on hover and keyboard focus. `false`: the ring is an image named with every stage and its state, with no button and no tooltip, for a ring inside a link or a card that is one link, such as PortfolioCard's `progress`. The line beside it is drawn either way.
classNamestring | undefined—Classes for the root, merged with Candor's.

Strings

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

KeyEnglish
stagesStages
name{label}: {stages}
stage{stage}, {state}
separator;
line{stage} · {state}
lineSeparator ·
othersFailed{ one: "{count} failed", other: "{count} failed" }
othersWaiting{ one: "{count} needs you", other: "{count} need you" }
detail{stage}: {detail}
allDoneAll done
noneNo stages