Skip to main content
Clever Ops

Percent Ring

Determinate loading ring, hairline token track, primary arc, tabular mono percent at center and a micro-label beneath. Falls back to an orbiting indeterminate segment when no progress is given.

Preview & code

Loading Percent Ring preview

Installation

pnpm dlx shadcn@latest add @cleverui/loader-percent-ring

Requires the @cleverui registry in your components.json, a one-off, two-line setup.

Usage

tsx
import { LoaderPercentRing } from '@/components/ui/loader-percent-ring'
Exampletsx
'use client'

import { useEffect, useState } from 'react'
import { useReducedMotion } from 'motion/react'
import { LoaderPercentRing } from '@/components/ui/loader-percent-ring'

export default function LoaderPercentRingDemo() {
  const reduced = useReducedMotion()
  const [progress, setProgress] = useState(0.12)

  useEffect(() => {
    if (reduced) {
      setProgress(0.47)
      return
    }
    const start = performance.now()
    let raf = 0
    const tick = (now: number) => {
      const t = Math.min(1, (now - start) / 4800)
      setProgress(0.12 + t * 0.78)
      if (t < 1) raf = requestAnimationFrame(tick)
    }
    raf = requestAnimationFrame(tick)
    return () => cancelAnimationFrame(raf)
  }, [reduced])

  return (
    <div className="mx-auto flex min-h-[360px] max-w-lg flex-col items-center justify-center gap-12 px-6 py-20">
      <div className="flex w-full max-w-sm flex-col gap-10">
        <div className="flex flex-col items-center gap-3 rounded-2xl border border-border/60 bg-card px-6 py-8">
          <p className="font-mono text-[11px] uppercase tracking-[0.2em] text-muted-foreground">
            Determinate
          </p>
          <LoaderPercentRing
            progress={progress}
            label="Indexing archive"
            size={72}
          />
          <p className="max-w-xs text-center text-sm leading-relaxed text-muted-foreground">
            Building the searchable trial balance for the March close pack,
            1,284 journal lines.
          </p>
        </div>

        <div className="flex flex-col items-center gap-3 rounded-2xl border border-border/60 bg-card px-6 py-8">
          <p className="font-mono text-[11px] uppercase tracking-[0.2em] text-muted-foreground">
            Indeterminate
          </p>
          <LoaderPercentRing label="Waiting on feed" size={72} />
          <p className="max-w-xs text-center text-sm leading-relaxed text-muted-foreground">
            Meridian bank feed has not published the 09:00 batch yet, holding
            the reconcile queue.
          </p>
        </div>
      </div>
    </div>
  )
}

API reference

LoaderPercentRing accepts the following props.

PropTypeDefaultDescription
progressnumberdeterminate 0 to 1; omit for the indeterminate spinner fallback
labelstring'Loading'mono micro-label beneath the ring; also seeds the aria announcement
sizenumber64ring diameter in px

…plus everything from React.HTMLAttributes<HTMLDivElement>: className, event handlers, aria attributes and the rest pass straight through.

Frequently asked questions

How do I install the Percent Ring component?

Register the @cleverui registry in your components.json ("@cleverui": "https://cleverops.com.au/r/{name}.json"), then run `npx shadcn@latest add @cleverui/loader-percent-ring`. The shadcn CLI copies the source into your project, you own the code from that point. You can also copy the source directly from this page.

What dependencies does Percent Ring require?

Percent Ring uses motion on top of React and Tailwind CSS. You don't need to install it manually, the shadcn CLI resolves and installs npm dependencies automatically when you add the component.

Can I theme Percent Ring to match my brand?

Yes. The component is styled entirely with Tailwind utilities over standard design tokens (primary, background, muted, border), so it inherits your existing shadcn/ui theme automatically. Change your CSS variables and the component follows, no source edits needed for palette, radius, or fonts.

Want this built for you?

CleverUI is built by the Clever Ops web team. If you'd rather ship a hand-coded, fast, custom website than assemble one, we build them for Australian businesses every week.

Explore web development services