Usage meter

Installation

$ npx shadcn@latest add https://goodui.dev/r/meter.json

The file lands in components/goodui/meter.tsx and is yours to edit. With the @goodui registry added, npx shadcn@latest add @goodui/meter works too.

Usage

import { Meter, type MeterTone } from "@/components/goodui/meter"

function smsHint({ tone, percent }: { tone: MeterTone; percent: number }) {
  if (tone === "danger") return `${percent}% used. Reminders pause at 10,000. Top up to keep them sending.`
  if (tone === "warning") return `${percent}% used. At this pace you run out before Dec 1.`
  return `${percent}% used. Renews Dec 1.`
}

export function PlanUsage({ sms, storageGb, seats }: { sms: number; storageGb: number; seats: number }) {
  return (
    <div className="flex flex-col gap-5 rounded-xl border bg-card p-5">
      <Meter label="SMS credits" value={sms} max={10000} hint={smsHint} />
      <Meter
        label="Photo storage"
        value={storageGb}
        max={20}
        unit=" GB"
        format={{ minimumFractionDigits: 1, maximumFractionDigits: 1 }}
      />
      <Meter label="Team seats" value={seats} max={10} segments={10} size="lg" hint={`${10 - seats} seats left`} />
    </div>
  )
}

When to use

Examples

<Meter
  label="API requests this month"
  value={84210}
  max={100000}
  warnAt={0.6}
  dangerAt={0.85}
  format={{ notation: "compact" }}
  size="sm"
/>

API reference

Accessibility

• •The bar is role="meter" with aria-valuemin 0, aria-valuemax max and aria-valuenow, and is named by the label through aria-labelledby.
• •aria-valuetext reads "7,420 of 10,000, 74%" (with the unit after max). Translate it with labels.valueText(value, max, percent).
• •The visible numbers use number-flow, which keeps one sr-only copy of the value; the " / max" text is aria-hidden because the meter already announces it.
• •Tone is never the only signal: the numbers and percent are always shown, and hint can say it in words.

Motion

• •The fill is translated (not resized) on a spring (stiffness 120, damping 20, mass 0.9). With segments, each segment starts 25 ms after the previous one.
• •The value digits roll through number-flow; the fill and hint colors cross-fade over 500 ms when the tone changes.
• •At 0 the fill fades out (150 ms after a 300 ms delay) so no sliver stays at the track edge.
• •Reduced motion: the fill and digits jump to the new value with duration 0.

Notes for AI

Coding agents read these rules through MCP and llms.txt, or paste this page with Copy page.

FAQ

Related