> ## 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.
# UsageTrend
> A bar chart of past billing periods: the amount of each period, or the units of one feature.
`UsageTrend` draws one bar per past billing period, oldest first, labelled with the period's start date and its amount or units. From React `0.11.0`.
**When to use**
* A usage history section of your billing settings.
* Beside [`UsageBreakdown`](/sdks/react/components/usage-breakdown) to compare this period with earlier ones.
* A chart of one feature's units over time, with `featureCode`.
**Light**
**Dark**
**Minimal**
**Neobrutal**
**Nozle**
**Nozle Dark**
## Importing UsageTrend
```tsx theme={null}
import {
UsageTrend,
useUsage,
type CustomerUsageData,
} from '@nozle-js/react'
```
## Rendering UsageTrend
Inside a `BillingProvider` with `billingEndpoint`, read past periods with `useUsage({ period: 'past' })` and pass them in:
```tsx app/billing/history/page.tsx theme={null}
'use client'
import { BillingProvider } from '@nozle-js/react'
function History() {
const { data, isPending, error } = useUsage({ period: 'past', periods: 6 })
return
}
export default function HistoryPage() {
return (
)
}
```
Periods can come in any order; they are sorted by start date. Bars scale to the largest period, and each bar has an accessible label with its date and value. Dates show in UTC in `en-US`.
## Data
`periods` is a list of `CustomerUsageData`, one per billing period, as in the `usage_periods` of Core's past-usage endpoint. Amounts are in cents; `units` is a decimal string.
```tsx theme={null}
const period = (from: string, to: string, apiCalls: number): CustomerUsageData => ({
from_datetime: from,
to_datetime: to,
currency: 'USD',
amount_cents: Math.round(apiCalls * 0.04),
charges_usage: [
{
units: String(apiCalls),
amount_cents: Math.round(apiCalls * 0.04),
amount_currency: 'USD',
charge: { nozle_id: `chg_${from}`, charge_model: 'standard' },
feature: { nozle_id: 'ftr_api', code: 'api_calls', name: 'API calls' },
},
],
})
const periods: CustomerUsageData[] = [
period('2026-08-01T00:00:00Z', '2026-08-31T23:59:59Z', 26400),
period('2026-09-01T00:00:00Z', '2026-09-30T23:59:59Z', 29800),
]
export function History() {
return
}
```
> **Full example data**
>
> ```tsx theme={null}
> const period = (from: string, to: string, apiCalls: number): CustomerUsageData => ({
> from_datetime: from,
> to_datetime: to,
> currency: 'USD',
> amount_cents: Math.round(apiCalls * 0.04),
> charges_usage: [
> {
> units: String(apiCalls),
> amount_cents: Math.round(apiCalls * 0.04),
> amount_currency: 'USD',
> charge: { nozle_id: `chg_${from}`, charge_model: 'standard' },
> feature: { nozle_id: 'ftr_api', code: 'api_calls', name: 'API calls' },
> },
> ],
> })
>
> const periods: CustomerUsageData[] = [
> period('2026-07-01T00:00:00Z', '2026-07-31T23:59:59Z', 22100),
> period('2026-08-01T00:00:00Z', '2026-08-31T23:59:59Z', 26400),
> period('2026-09-01T00:00:00Z', '2026-09-30T23:59:59Z', 29800),
> ]
>
> export function History() {
> return (
> <>
>
>
>
> )
> }
> ```
### Live data
[`useUsage({ period: 'past' })`](/sdks/react/hooks#the-hooks) reads past periods for the signed-in customer through your `billingEndpoint`; `periods` sets how many. Its `data` is the list of periods and passes to `periods` directly:
```tsx theme={null}
export function LiveTrend() {
const { data, isPending, error } = useUsage({ period: 'past', periods: 6 })
return
}
```
Without the hooks, read `GET https://api.nozle.app/core/api/v1/customers/{external_customer_id}/past_usage` on your backend with a secret key and pass its `usage_periods`. It takes `periods_count` and `feature_code`.
## Examples
### Units of one feature
With `featureCode`, each bar shows that feature's units in the period instead of the amount, for example "29,800 api\_calls". Periods without the feature show zero.
```tsx theme={null}
export function ApiCallsTrend() {
const { data, isPending, error } = useUsage({ period: 'past', periods: 6 })
return
}
```
### Loading, empty and error
`isLoading` shows a loading placeholder, an empty list shows `emptyMessage`, and `error` shows the message as an alert.
```tsx theme={null}
export function TrendStates() {
return (
<>
)
}
```
## API reference
**periods** `CustomerUsageData[] | null`
The periods to chart, in any order. Empty or missing shows the empty message.
**featureCode** `string`
Charts the units of this feature instead of the amount. Bars read "29,800 api\_calls".
**isLoading** `boolean` (default: false)
Shows a loading placeholder.
**error** `Error | string | null`
Shows the message as an alert. Defaults to `null`.
**emptyMessage** `string` (default: No past usage yet.)
Shown when there are no periods.
**appearance** `Appearance`
Theme, variables and element overrides. Defaults to the provider's. See [Appearance](/sdks/react/styling).
### States
| State | What shows |
| - | - |
| `isLoading` | A skeleton placeholder with `role="status"`. |
| `error` set | The message in a `role="alert"` card, in the danger text colour. |
| No periods | `emptyMessage`. |
### Appearance
> **Element keys**
>
> `usageTrend` (root), `usageTrend__bar` (each bar).
>
> Style them with `appearance.elements`. See [Elements](/sdks/react/styling#elements).
## Related
> **[UsageBreakdown](/sdks/react/components/usage-breakdown)**
>
> This period's units and amounts.
> **[UsageDashboard](/sdks/react/components/usage-dashboard)**
>
> Usage against limits.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.