UsageMeter

UsageMeter shows how much of one limit is used: a label, used / limit, and a bar that turns amber at 80% and red at 95%. When to use

Next to a feature that has a monthly limit (“API calls this month”).
In a settings page, one row per limit.
Anywhere you need the same warning colours as the meter, through getUsageMeterColor.

For several limits at once, use UsageDashboard.

Four UsageMeters: normal at 42%, warning at 86%, critical at 98%, and unlimited, light theme

Importing UsageMeter

import {
  UsageMeter,
  getUsageMeterColor,
  type UsageMeterProps,
} from '@nozle-js/react'

Rendering UsageMeter

Pass the usage so far and the limit:

components/api-calls-meter.tsx

export function ApiCallsMeter() {
  return <UsageMeter label="API calls" used={4200} limit={10000} />
}

The bar fills to the share of the limit used, capped at 100%. It uses the primary colour below 80%, the warning colour from 80% and the danger colour from 95%; the used / limit text takes the same colour.

Data

The meter needs two numbers: used and limit. A limit of null means the feature has no limit.

export function Meters() {
  return (
    <>
      <UsageMeter label="API calls" used={4200} limit={10000} />
      <UsageMeter label="Seats" used={9} limit={10} />
      <UsageMeter label="Projects" used={12} limit={null} />
      <UsageMeter used={9800} limit={10000} />
    </>
  )
}

Live data

useEntitlement(featureCode) returns the can() result for the signed-in customer through your billingEndpoint, with used and limit:

import { useEntitlement } from '@nozle-js/react'

export function ApiCallsMeter() {
  const { data } = useEntitlement('api_calls')
  if (!data) return null
  return <UsageMeter label="API calls" used={data.used ?? 0} limit={data.limit} />
}

Examples

Warning and danger colours

From 80% the bar and the numbers turn amber; from 95% they turn red.

export function Meters() {
  return (
    <>
      <UsageMeter label="Normal" used={4200} limit={10000} />
      <UsageMeter label="Warning" used={8600} limit={10000} />
      <UsageMeter label="Critical" used={9800} limit={10000} />
    </>
  )
}

Unlimited

With limit set to null or left out, the text reads “Unlimited” and the bar stays empty.

export function ProjectsMeter() {
  return <UsageMeter label="Projects" used={12} limit={null} />
}

Bar only

Without label, only the bar shows.

export function CompactMeter() {
  return <UsageMeter used={9800} limit={10000} />
}

The meter colour in your own UI

getUsageMeterColor(percentage) returns the fill colour for a percentage, as a CSS value: colorDanger at 95 or more, colorWarning at 80 or more, otherwise colorPrimary.

export function UsagePercent({ percentage }: { percentage: number }) {
  return <span style={{ color: getUsageMeterColor(percentage) }}>{percentage}% used</span>
}

API reference

number

required

The usage so far.

number | null

The limit. null or no value means unlimited: the text reads “Unlimited” and the bar stays empty. A limit of 0 shows an empty bar.

string

Text above the bar. Without it, only the bar shows.

boolean

default:true

Shows used / limit on the right of the label. Numbers use the browser’s locale.

Appearance

Theme, variables and element overrides. Defaults to the provider’s. See Appearance.

States

State	What shows
Below 80%	The bar in the primary colour.
80% to 94%	The bar and numbers in the warning colour.
95% or more	The bar and numbers in the danger colour.
No limit	”Unlimited” and an empty bar.

Appearance

Element keys

usageMeter (root), usageMeter__label, usageMeter__value, usageMeter__track, usageMeter__fill.Style them with appearance.elements. See Elements.

UsageDashboard

Several meters in one card.

UsageAlert

A warning when a limit is close.

UsageGate

Hides a feature at the limit.

Setup

Components

Billing

Entitlements

Importing UsageMeter

Rendering UsageMeter

Data

Live data

Examples

Warning and danger colours

Unlimited

Bar only

The meter colour in your own UI

API reference

States

Appearance

UsageDashboard

UsageAlert

UsageGate

​Importing UsageMeter

​Rendering UsageMeter

​Data

​Live data

​Examples

​Warning and danger colours

​Unlimited

​Bar only

​The meter colour in your own UI

​API reference

​States

​Appearance

​Related

UsageDashboard

UsageAlert

UsageGate

Importing UsageMeter

Rendering UsageMeter

Data

Live data

Examples

Warning and danger colours

Unlimited

Bar only

The meter colour in your own UI

API reference

States

Appearance

Related