> ## 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.
# UsageBreakdown
> A table of the current billing period's usage: units and amount per feature, and the total.
`UsageBreakdown` shows one billing period's usage as a table: each feature's units and amount, largest amount first, and the period total. From React `0.11.0`.
**When to use**
* A "Usage this period" section of your billing settings.
* Next to [`CurrentPlan`](/sdks/react/components/current-plan), to explain the next invoice.
* Any place that needs the period's dates, one row per charge and a total row.
**Light**
**Dark**
**Minimal**
**Neobrutal**
**Nozle**
**Nozle Dark**
## Importing UsageBreakdown
```tsx theme={null}
import {
UsageBreakdown,
useUsage,
type CustomerUsageData,
} from '@nozle-js/react'
```
## Rendering UsageBreakdown
Inside a `BillingProvider` with `billingEndpoint`, read the current period with `useUsage` and pass it in:
```tsx app/billing/usage/page.tsx theme={null}
'use client'
import { BillingProvider } from '@nozle-js/react'
function ThisPeriod() {
const { data, isPending, error } = useUsage()
return
}
export default function UsagePage() {
return (
)
}
```
Each row shows the charge's invoice name when set, otherwise the feature name. Units show as exact decimals, up to six places, and amounts in the period's currency. Dates show in UTC in `en-US` ("Oct 1, 2026 to Oct 31, 2026").
## Data
`usage` is the `customer_usage` object of Core's current-usage endpoint. Amounts are in cents; `units` is a decimal string.
```tsx theme={null}
const usage: CustomerUsageData = {
from_datetime: '2026-10-01T00:00:00Z',
to_datetime: '2026-10-31T23:59:59Z',
currency: 'USD',
amount_cents: 1248,
charges_usage: [
{
units: '31200',
amount_cents: 1248,
amount_currency: 'USD',
charge: { nozle_id: 'chg_api', charge_model: 'standard', invoice_display_name: null },
feature: { nozle_id: 'ftr_api', code: 'api_calls', name: 'API calls' },
},
],
}
export function ThisPeriod() {
return
}
```
> **Full example data**
>
> ```tsx theme={null}
> const usage: CustomerUsageData = {
> from_datetime: '2026-10-01T00:00:00Z',
> to_datetime: '2026-10-31T23:59:59Z',
> currency: 'USD',
> amount_cents: 1788,
> charges_usage: [
> {
> units: '31200',
> amount_cents: 1248,
> amount_currency: 'USD',
> charge: { nozle_id: 'chg_api', charge_model: 'standard', invoice_display_name: null },
> feature: { nozle_id: 'ftr_api', code: 'api_calls', name: 'API calls' },
> },
> {
> units: '9',
> amount_cents: 540,
> amount_currency: 'USD',
> charge: { nozle_id: 'chg_seats', charge_model: 'standard', invoice_display_name: 'Seats' },
> feature: { nozle_id: 'ftr_seats', code: 'seats', name: 'Seats' },
> },
> ],
> }
>
> export function ThisPeriod() {
> return
> }
> ```
### Live data
Inside a `BillingProvider` with `billingEndpoint`, [`useUsage()`](/sdks/react/hooks#the-hooks) reads the current period for the signed-in customer. Its `data` passes to `usage` directly:
```tsx theme={null}
export function LiveBreakdown() {
const { data, isPending, error } = useUsage()
return
}
```
Without the hooks, read `GET https://api.nozle.app/core/api/v1/customers/{external_customer_id}/current_usage` on your backend with a secret key and pass its `customer_usage`. Add `external_subscription_id` when the customer has more than one subscription.
## Examples
### Loading, empty and error
`isLoading` shows a loading placeholder, a period without charges shows `emptyMessage`, and `error` shows the message as an alert.
```tsx theme={null}
export function BreakdownStates() {
return (
<>
)
}
```
## API reference
**usage** `CustomerUsageData | null`
The period: `from_datetime`, `to_datetime`, `currency`, `amount_cents` and `charges_usage`. Without charges it shows the empty message.
**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 usage in this period yet.)
Shown when there is no usage.
**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 `usage`, or no charges | `emptyMessage`. |
### Appearance
> **Element keys**
>
> `usageBreakdown` (root), `usageBreakdown__row` (each charge row).
>
> Style them with `appearance.elements`. See [Elements](/sdks/react/styling#elements).
## Related
> **[UsageTrend](/sdks/react/components/usage-trend)**
>
> Past periods as bars.
> **[UsageDashboard](/sdks/react/components/usage-dashboard)**
>
> Usage against limits.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.