> ## 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.
# UsageMeter
> A progress bar for one feature's usage against its limit, coloured by how close it is.
`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`](/sdks/react/components/usage-dashboard).
**Light**
**Dark**
**Minimal**
**Neobrutal**
**Nozle**
**Nozle Dark**
## Importing UsageMeter
```tsx theme={null}
import {
UsageMeter,
getUsageMeterColor,
type UsageMeterProps,
} from '@nozle-js/react'
```
## Rendering UsageMeter
Pass the usage so far and the limit:
```tsx components/api-calls-meter.tsx theme={null}
export function ApiCallsMeter() {
return
}
```
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.
```tsx theme={null}
export function Meters() {
return (
<>
)
}
```
### Live data
[`useEntitlement(featureCode)`](/sdks/react/hooks#the-hooks) returns the `can()` result for the signed-in customer through your `billingEndpoint`, with `used` and `limit`:
```tsx theme={null}
import { useEntitlement } from '@nozle-js/react'
export function ApiCallsMeter() {
const { data } = useEntitlement('api_calls')
if (!data) return null
return
}
```
## Examples
### Warning and danger colours
From 80% the bar and the numbers turn amber; from 95% they turn red.
```tsx theme={null}
export function Meters() {
return (
<>
)
}
```
### Unlimited
With `limit` set to `null` or left out, the text reads "Unlimited" and the bar stays empty.
```tsx theme={null}
export function ProjectsMeter() {
return
}
```
### Bar only
Without `label`, only the bar shows.
```tsx theme={null}
export function CompactMeter() {
return
}
```
### 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`.
```tsx theme={null}
export function UsagePercent({ percentage }: { percentage: number }) {
return {percentage}% used
}
```
## API reference
**used** `number` *required*
The usage so far.
**limit** `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.
**label** `string`
Text above the bar. Without it, only the bar shows.
**showText** `boolean` (default: true)
Shows `used / limit` on the right of the label. Numbers use the browser's locale.
**appearance** `Appearance`
Theme, variables and element overrides. Defaults to the provider's. See [Appearance](/sdks/react/styling).
### 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](/sdks/react/styling#elements).
## Related
> **[UsageDashboard](/sdks/react/components/usage-dashboard)**
>
> Several meters in one card.
> **[UsageAlert](/sdks/react/components/usage-alert)**
>
> A warning when a limit is close.
> **[UsageGate](/sdks/react/components/usage-gate)**
>
> Hides a feature at the limit.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.