UsageAlert

UsageAlert shows one warning per feature at or above a usage threshold, each with an “Upgrade” link and a dismiss button. When to use

The top of your app’s main page or dashboard.
Above a feature that is close to its limit.
Any place where you want a warning only once usage passes a threshold you choose.

Two UsageAlert warnings for seats at 90% and storage at 98%, light theme

Importing UsageAlert

import { UsageAlert, type UsageAlertFeature } from '@nozle-js/react'

Rendering UsageAlert

Pass each feature with its usage percentage:

components/usage-alerts.tsx

export function UsageAlerts() {
  return (
    <UsageAlert
      features={[{ key: 'seats', label: 'Seats', percentage: 90 }]}
      upgradeHref="/settings/billing/plans"
    />
  )
}

Each warning reads “You’re approaching your <feature> limit (N%). Upgrade”. The component renders nothing when no feature is at or above the threshold.

Data

Each feature is a UsageAlertFeature: { key, label, percentage }. Features below the threshold are left out:

const features: UsageAlertFeature[] = [
  { key: 'seats', label: 'Seats', percentage: 90 },
  { key: 'storage', label: 'Storage', percentage: 98 },
  { key: 'api_calls', label: 'API calls', percentage: 40 },
]

export function Alerts() {
  return <UsageAlert features={features} threshold={80} upgradeHref="/settings/billing/plans" />
}

Only Seats and Storage show here; API calls is below the threshold.

Live data

Work out the percentage from the used and limit of useEntitlement:

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

export function SeatsAlert() {
  const { data } = useEntitlement('seats')
  const features: UsageAlertFeature[] =
    data && data.limit ? [{ key: 'seats', label: 'Seats', percentage: ((data.used ?? 0) / data.limit) * 100 }] : []
  return <UsageAlert features={features} />
}

Examples

Several features

Each feature at or above the threshold gets its own warning. Raise threshold to warn later: with threshold={95}, only Storage would show here.

export function QuotaAlerts() {
  return (
    <UsageAlert
      features={[
        { key: 'seats', label: 'Seats', percentage: 90 },
        { key: 'storage', label: 'Storage', percentage: 98 },
      ]}
    />
  )
}

API reference

UsageAlertFeature[]

required

{ key, label, percentage } per feature. The percentage is rounded in the text.

number

default:80

A feature at or above this percentage shows a warning.

string

default:"/plans"

Where the “Upgrade” link goes.

Appearance

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

States

State	What shows
No feature at or above `threshold`	Nothing.
One or more features over	One `role="alert"` warning per feature, in the warning colours.
Warning dismissed	That warning hides, for as long as the component stays mounted.

Dismissed warnings are kept in component state, keyed by key; they come back when the component mounts again.

Appearance

Element keys

usageAlert (root), usageAlert__dismiss (the × button).Style them with appearance.elements. See Elements.

UsageMeter

The usage of one limit as a bar.

UpgradeButton

Upgrade from the warning.

Setup

Components

Billing

Entitlements

Importing UsageAlert

Rendering UsageAlert

Data

Live data

Examples

Several features

API reference

States

Appearance

UsageMeter

UpgradeButton

​Importing UsageAlert

​Rendering UsageAlert

​Data

​Live data

​Examples

​Several features

​API reference

​States

​Appearance

​Related

UsageMeter

UpgradeButton

Importing UsageAlert

Rendering UsageAlert

Data

Live data

Examples

Several features

API reference

States

Appearance

Related