> ## 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.
# CreditBalance
> One credit balance: credits available, the time of the reading, and where the credits come from.
`CreditBalance` shows how many credits a customer has in one credit system, and the grants and top-ups they come from. From React `0.11.0`.
**When to use**
* Next to an AI or credit-metered feature, so customers see what is left.
* The credits section of your billing settings, with [`CreditHistory`](/sdks/react/components/credit-history) below it.
* Any place that shows what remains of each grant or top-up and when it expires.
**Light**
**Dark**
**Minimal**
**Neobrutal**
**Nozle**
**Nozle Dark**
## Importing CreditBalance
```tsx theme={null}
import {
CreditBalance,
useCreditBalance,
type CreditBalanceData,
type CreditBalanceSource,
} from '@nozle-js/react'
```
## Rendering CreditBalance
Inside a `BillingProvider` with `billingEndpoint`, read the balance with `useCreditBalance` and pass it in:
```tsx app/billing/credits/page.tsx theme={null}
'use client'
import { BillingProvider } from '@nozle-js/react'
function AiCredits() {
const { data, isPending, error } = useCreditBalance('ai_credits')
return
}
export default function CreditsPage() {
return (
)
}
```
The card shows the available credits with the unit name, singular for exactly 1 ("1 credit available", "1,240 credits available"), and "As of \" for the time of the reading. Below it, one line per source shows what remains and when it expires.
## Data
`balance` is a `CreditBalanceData`. Credit amounts are decimal strings.
```tsx theme={null}
const balance: CreditBalanceData = {
credit_system_name: 'AI credits',
unit_name: 'credit',
available: '1240',
as_of: '2026-10-16T09:00:00Z',
sources: [
{ id: 'grant_1', type: 'subscription_grant', remaining: '500', expires_at: '2026-11-01T00:00:00Z' },
{ id: 'topup_1', type: 'top_up', remaining: '740', expires_at: null },
],
}
export function Credits() {
return
}
```
### Live data
Inside a `BillingProvider` with `billingEndpoint`, [`useCreditBalance(creditSystemCode?)`](/sdks/react/hooks#the-hooks) returns one balance of the signed-in customer: the given credit system, else the first one with credits, else the first one.
```tsx theme={null}
export function AiCredits() {
const { data, isPending, error } = useCreditBalance('ai_credits')
return
}
```
Without the hooks, pass one entry of the SDK's `credits.balance` result, read on your backend.
### Source types
Each source's `type` sets its label. A source type the component does not know shows as sent. Sources whose `remaining` is `"0"` are hidden.
| `type` | Label |
| - | - |
| `subscription_grant` | Plan grant |
| `top_up` | Top-up |
| `manual_grant` | Granted |
| `adjustment` | Adjustment |
| `allocated_top_up` | Allocated top-up |
## Examples
### Loading, empty and error
`isLoading` shows a loading placeholder, no `balance` shows `emptyMessage`, and `error` shows the message as an alert.
```tsx theme={null}
export function BalanceStates() {
return (
<>
)
}
```
## API reference
**balance** `CreditBalanceData | null`
`null` or no value shows the empty message.
**properties**
**credit\_system\_name** `string` *required*
Heading of the card.
**unit\_name** `string` *required*
Singular unit name, for example `credit`. An `s` is added unless `available` is exactly 1.
**available** `string` *required*
Credits available, as a decimal string.
**as\_of** `string` *required*
Time of the reading, shown as "As of \".
**sources** `CreditBalanceSource[]`
Where the credits come from: `id`, `type`, `remaining` and `expires_at`. See [Source types](#source-types).
**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 credit balance yet.)
Shown when there is no balance.
**appearance** `Appearance`
Theme, variables and element overrides. Defaults to the provider's. See [Appearance](/sdks/react/styling).
Dates show in `en-US` ("Oct 16, 2026").
### 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 `balance` | `emptyMessage`. |
### Appearance
> **Element keys**
>
> `creditBalance` (root), `creditBalance__amount` (the large number).
>
> Style them with `appearance.elements`. See [Elements](/sdks/react/styling#elements).
## Related
> **[CreditHistory](/sdks/react/components/credit-history)**
>
> How credits were used and granted.
> **[Credits](/guides/credits/overview)**
>
> How credit systems work.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.