UsageDashboard

UsageDashboard shows several UsageMeters in one card, one per feature. When to use

A “Usage” tab in your billing or account settings.
A dashboard card that shows the customer’s limits.
Several limits at once, limited and unlimited, with the meter’s colour thresholds.

UsageDashboard with API calls at 62%, seats at 90% and storage at 98%, light theme

Importing UsageDashboard

import {
  UsageDashboard,
  usageItems,
  type UsageDashboardFeature,
  type UsageResult,
} from '@nozle-js/react'

Rendering UsageDashboard

Pass one row per feature:

components/usage-card.tsx

export function UsageCard() {
  return (
    <UsageDashboard
      features={[
        { key: 'api_calls', label: 'API calls', used: 31200, limit: 50000 },
        { key: 'seats', label: 'Seats', used: 9, limit: 10 },
      ]}
    />
  )
}

Each row renders a labelled UsageMeter with its colour thresholds.

Data

Each row is a UsageDashboardFeature: { key, label, used, limit? }. A limit of null, or no limit, means unlimited.

const features: UsageDashboardFeature[] = [
  { key: 'api_calls', label: 'API calls', used: 31200, limit: 50000 },
  { key: 'projects', label: 'Projects', used: 12, limit: null },
]

export function Usage() {
  return <UsageDashboard features={features} />
}

Full example data

const features: UsageDashboardFeature[] = [
  { key: 'api_calls', label: 'API calls', used: 31200, limit: 50000 },
  { key: 'seats', label: 'Seats', used: 9, limit: 10 },
  { key: 'storage', label: 'Storage (GB)', used: 98, limit: 100 },
  { key: 'projects', label: 'Projects', used: 12, limit: null },
]

export function Usage() {
  return <UsageDashboard features={features} />
}

Live data

usageItems(entitlements, results) joins a plan’s metered entitlements from the catalog (for the names) with usage results keyed by feature code, the used and limit of a can() result. Entitlements that are not metered, or have no result, are left out.

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

export function LiveUsage() {
  const subscription = useSubscription()
  const { plans } = usePlans()
  const apiCalls = useEntitlement('api_calls')
  const seats = useEntitlement('seats')

  const plan = plans.find((entry) => entry.code === subscription.data?.subscription?.plan_code)
  const results: Record<string, UsageResult | undefined> = {
    api_calls: apiCalls.data && { used: apiCalls.data.used ?? 0, limit: apiCalls.data.limit },
    seats: seats.data && { used: seats.data.used ?? 0, limit: seats.data.limit },
  }
  return (
    <UsageDashboard
      features={usageItems(plan?.entitlements ?? [], results)}
      loading={subscription.isPending || apiCalls.isPending || seats.isPending}
      error={subscription.error ?? apiCalls.error ?? seats.error}
    />
  )
}

currentPlanMeters(entitlements, usage) builds the same rows from this period’s charges_usage instead; see CurrentPlan.

Examples

Loading, empty and error

loading shows three skeleton rows, an empty features list shows emptyMessage, and error shows the message instead of the rows.

UsageDashboard skeleton, No usage to show yet message, and an error message, light theme

export function UsageStates() {
  return (
    <>
      <UsageDashboard loading />
      <UsageDashboard features={[]} />
      <UsageDashboard error="Usage could not be loaded." />
    </>
  )
}

Unlimited feature

A row without a limit reads “Unlimited” and its bar stays empty.

export function ProjectsUsage() {
  return <UsageDashboard features={[{ key: 'projects', label: 'Projects', used: 12, limit: null }]} />
}

API reference

UsageDashboardFeature[]

The rows: { key, label, used, limit? }. limit null or missing means unlimited. Defaults to [].

boolean

default:false

Shows three skeleton rows.

Error | string | null

Shows the message in a role="alert" card instead of the rows. Defaults to null.

string

default:"No usage to show yet."

Shown when features is empty.

Appearance

Theme, variables and element overrides, also passed to each meter. Defaults to the provider’s. See Appearance.

States

State	What shows
`loading`	Three skeleton rows.
`error` set	The message in a `role="alert"` card, in the danger text colour.
No features	`emptyMessage` in a `role="status"` card.

Appearance

Element keys

usageDashboard (the card), and the UsageMeter elements for each row.Style them with appearance.elements. See Elements.

UsageMeter

One meter on its own.

UsageBreakdown

Units and amounts of this period.

CurrentPlan

The plan with its meters built for you.

UsageAlert

A warning when a limit is close.

Setup

Components

Billing

Entitlements

UsageDashboard

Importing UsageDashboard

Rendering UsageDashboard

Data

Live data

Examples

Loading, empty and error

Unlimited feature

API reference

States

Appearance

UsageMeter

UsageBreakdown

CurrentPlan

UsageAlert

​Importing UsageDashboard

​Rendering UsageDashboard

​Data

​Live data

​Examples

​Loading, empty and error

​Unlimited feature

​API reference

​States

​Appearance

​Related

UsageMeter

UsageBreakdown

CurrentPlan

UsageAlert

Importing UsageDashboard

Rendering UsageDashboard

Data

Live data

Examples

Loading, empty and error

Unlimited feature

API reference

States

Appearance

Related