Show usage limits in your app

Where an entitlement is a yes/no switch, a quota is a metered allowance that a workspace (called a tenant in the API) can run down and hit: 10,000 AI calls a month, 20 seats. Quotas are defined on the plan; see Define your plans for setting them. This page covers showing quota state in your app and reacting as usage climbs. To submit the usage that fills these quotas, see Report usage.

<BridgeQuotaBanner> warns users as they approach a metric’s cap so a hard stop never comes as a surprise, and it nudges them to upgrade. It’s a live usage-cap banner for one metric: it renders nothing while usage is below 80% of the plan’s quota (or when the plan has no quota for that metric), shows a warning at 80–94%, critical at 95%+, and over-cap copy when the limit is exceeded. It updates live on quota.updated pushes.

import { BridgeQuotaBanner } from '@nebulr-group/bridge-react';

<BridgeQuotaBanner metric="ai_completions" />

| Prop | Type | Default | Description | |------|------|---------|-------------| | metric | string | required | Metric key to watch | | label | string | metric key | Humanized display label | | className | string | '' | Class applied to the root element | | onActionClick | (snap) => void | (none) | Override the default Upgrade CTA handler |

Reading quota state yourself

For a fully custom quota UI, read the underlying snapshot directly:

import { useBridgeBilling } from '@nebulr-group/bridge-react';

const q = useBridgeBilling().quota('ai_completions');
// undefined while loading (first call triggers a fetch), then:
// q?.used, q?.limit, q?.remaining, q?.warningLevel ('approaching' | 'critical' | null)

Note: useBridgeBilling is the React SDK’s re-export of the underlying @nebulr-group/bridge-auth-core package’s useBridge billing surface. It’s a temporary escape hatch: the React SDK doesn’t yet expose quota state on the bridge object (and the useBridge() exported by bridge-react is a different function that returns the bridge object, without a quota() method). Until the SDK surfaces quotas, use this re-export for this one read.