> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nozle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# UsageAlert

> Dismissible warnings for features whose usage has reached a threshold, with an upgrade link.

`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.

**Light**

![Two UsageAlert warnings for seats at 90% and storage at 98%, light theme](https://mintcdn.com/nozle-d78f01d8/8jEvxrWAvqijYzbo/images/react/components/usage-alert/light.png?fit=max\&auto=format\&n=8jEvxrWAvqijYzbo\&q=85\&s=30d79e25b86824aad69522d119d727e3)

**Dark**

![Two UsageAlert warnings for seats at 90% and storage at 98%, dark theme](https://mintcdn.com/nozle-d78f01d8/8jEvxrWAvqijYzbo/images/react/components/usage-alert/dark.png?fit=max\&auto=format\&n=8jEvxrWAvqijYzbo\&q=85\&s=f22e3eca9e06441f0e26bf3d67448cc4)

**Minimal**

![Two UsageAlert warnings for seats at 90% and storage at 98%, minimal theme](https://mintcdn.com/nozle-d78f01d8/8jEvxrWAvqijYzbo/images/react/components/usage-alert/minimal.png?fit=max\&auto=format\&n=8jEvxrWAvqijYzbo\&q=85\&s=cbef4500718c4c0d983997a05736dc98)

**Neobrutal**

![Two UsageAlert warnings for seats at 90% and storage at 98%, neobrutal theme](https://mintcdn.com/nozle-d78f01d8/8jEvxrWAvqijYzbo/images/react/components/usage-alert/neobrutal.png?fit=max\&auto=format\&n=8jEvxrWAvqijYzbo\&q=85\&s=b09136eb9095fed834a957917c9de196)

**Nozle**

![Two UsageAlert warnings for seats at 90% and storage at 98%, nozle theme](https://mintcdn.com/nozle-d78f01d8/8jEvxrWAvqijYzbo/images/react/components/usage-alert/nozle.png?fit=max\&auto=format\&n=8jEvxrWAvqijYzbo\&q=85\&s=e4db783f439d444f51a93d6aa3c2e07b)

**Nozle Dark**

![Two UsageAlert warnings for seats at 90% and storage at 98%, nozleDark theme](https://mintcdn.com/nozle-d78f01d8/8jEvxrWAvqijYzbo/images/react/components/usage-alert/nozle-dark.png?fit=max\&auto=format\&n=8jEvxrWAvqijYzbo\&q=85\&s=e04d01d70d78ec775f04f77daf125c2f)

## Importing UsageAlert

```tsx theme={null}
import { UsageAlert, type UsageAlertFeature } from '@nozle-js/react'
```

## Rendering UsageAlert

Pass each feature with its usage percentage:

```tsx components/usage-alerts.tsx theme={null}
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:

```tsx theme={null}
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`](/sdks/react/hooks#the-hooks):

```tsx theme={null}
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.

![Two UsageAlert warnings for seats at 90% and storage at 98%, light theme](https://mintcdn.com/nozle-d78f01d8/8jEvxrWAvqijYzbo/images/react/components/usage-alert/light.png?fit=max\&auto=format\&n=8jEvxrWAvqijYzbo\&q=85\&s=30d79e25b86824aad69522d119d727e3)

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

## API reference

**features** `UsageAlertFeature[]` *required*

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

**threshold** `number` (default: 80)

A feature at or above this percentage shows a warning.

**upgradeHref** `string` (default: /plans)

Where the "Upgrade" link goes.

**appearance** `Appearance`

Theme, variables and element overrides. Defaults to the provider's. See [Appearance](/sdks/react/styling).

### 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](/sdks/react/styling#elements).

## Related

> **[UsageMeter](/sdks/react/components/usage-meter)**
>
> The usage of one limit as a bar.

> **[UpgradeButton](/sdks/react/components/upgrade-button)**
>
> Upgrade from the warning.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.