Skip to content
rdloom

Usage Meter

A labeled meter for a limit: seats 8 of 10, storage 4.2 of 5 GB, API calls. It warns at 80 percent and at the limit with words and an icon, not only color, and can offer an upgrade when near the limit. UsageMeterList shows several. Built on role="meter"; the app owns the numbers. UI permission is not security: the server must check again.

Blockv0.1.0experimentalWCAG 2.2 AAView spec

A ready-made piece, built from the library's own parts.

A block puts several components together into something you would otherwise assemble by hand. It never fetches data: you give it the data, or answer its callbacks. It is copied into your project like any component, with the parts it uses, so you can change anything.

Basic

Full screen (opens in a new tab)
Seats6 of 10 seats

Add people in Members.

Thresholds

Full screen (opens in a new tab)
Seats6 of 10 seats
Storage4.2 of 5 GB

Near the limit

Projects10 of 10

Limit reached

API calls11,200 of 10,000

Over the limit

List

Full screen (opens in a new tab)
  • Seats8 of 10 seats

    Near the limit

  • Storage4.2 of 5 GB

    Near the limit

  • API calls6,200 of 10,000

    Resets on 1 March.

States

Full screen (opens in a new tab)

No usage to show yet

Meters appear here once there is something to measure.

Couldn't load usage

Permissions

Full screen (opens in a new tab)
Storage4.6 of 5 GB

Near the limit

Ask a billing owner to upgrade the plan.

ClassNames

Full screen (opens in a new tab)
Storage4.2 of 5 GB

Near the limit

Installation

npx rdloom add usage-meter

Copies the source into src/components/rdloom. Edit it freely: rdloom upgrade merges later versions into your changes.

Use another registry client
npx shadcn@latest add https://rdloom.vimalbhatt.com/r/usage-meter.json

Works, but without upgrade tracking.

Usage

import { UsageMeter } from "@rdloom/react";

<div className="flex w-full justify-center">
  <div className="w-full max-w-md">
    <UsageMeter label="Seats" value={6} limit={10} unit="seats" description="Add people in Members." />
  </div>
</div>

API Reference

Defined by the spec. Components also accept the props of the React Aria component they wrap.

PropTypeDefault
labelrequired

What is measured, e.g. "Seats". It is the accessible name.

stringnone
valuerequired

How much is used.

numbernone
limitrequired

The most the plan allows.

numbernone
unit

A unit shown after the numbers, e.g. "GB" or "seats".

stringnone
formatValue

Formats the numbers. Default: up to one decimal.

(value: number) => stringnone
description

A line under the meter, e.g. "Resets on 1 April".

stringnone
warningAt

The percentage from which the meter says it is near the limit.

number80
dangerAt

The percentage from which the meter says the limit is reached.

number100
onUpgrade

Shows an upgrade button when the meter is near the limit or over it; yours, async.

() => void | Promise<unknown>none
upgradeLabel

The text of the upgrade button.

string"Upgrade"
state

loading shows a skeleton and marks the meter busy; the other states show the meter.

DataStatenone
permissions

What the app allows: upgrade. Hidden renders nothing; disabled keeps the control reachable (aria-disabled) with the reason shown and read, and nothing runs. This only changes what people see: the server must check again.

Permissions<"upgrade">none
classNames

Extra class names for single parts, so you can restyle one part without editing the file. Keys: root, header, label, value, status, track, bar, description, upgradeButton.

Partial<Record<"root" | "header" | "label" | "value" | "status" | "track" | "bar" | "description" | "upgradeButton", string>>none

Accessibility

Role meter, WCAG 2.2 AA. Tested with axe and keyboard tests; screen reader checks are in the audit checklist.

Keyboard

  • Tab: moves to the upgrade button when it is shown

Screen readers announce

  • "Seats, meter, 8 of 10 seats, near the limit"
  • "Storage, meter, 5 of 5 GB, limit reached"
  • "Upgrade, button"

What your code must do

  • Has role meter with aria-valuemin, aria-valuemax and aria-valuenow, named by the label
  • aria-valuetext says the amounts and the status in words, e.g. "8 of 10 seats, near the limit"
  • Near the limit and at the limit are told by text and an icon as well as the bar color
  • The bar color has 3:1 contrast against the track
  • A value above the limit is shown as full and said as over the limit

Block contract

Data
A used amount and a limit with an optional unit.
Data states
loading, ready
Permissions
upgrade
Events
onUpgrade
You can replace
classNames for each part; warningAt and dangerAt; unit and formatValue; UsageMeterList for several meters

Guidelines

Use it when

  • Showing how much of a plan limit is used: seats, storage, API calls
  • Nudging an upgrade at the moment people need it

Avoid it when

  • Progress of a task that finishes: use Progress
  • A trend over time: use Chart or Sparkline

Don't

  • Treating the permissions prop as protection: UI permission is not security, so the server must check again
  • Computing usage in the component: the numbers are yours
  • Showing the warning by color alone: the text and icon are on purpose

Design tokens

The semantic tokens this component uses. Change them once and every component follows; see Design tokens.

  • --rd-color-action-primary
  • --rd-color-border-default
  • --rd-color-text-default
  • --rd-color-text-muted
  • --rd-color-feedback-warning
  • --rd-color-feedback-danger