> ## 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.
# CurrentPlan
> The customer's plan at a glance: name, status, price, a scheduled change, usage against the plan's limits and payment notices.
`CurrentPlan` shows the customer's subscription in one card, read through your `billingEndpoint` or from data you pass. From React `0.11.0`.
**When to use**
* The top of your billing settings page.
* A dashboard card that links to plan changes or the billing portal.
* Showing usage against the plan's metered limits next to the plan itself.
* Warning the customer about an overdue invoice or a nearly used limit.
**Light**
**Dark**
**Minimal**
**Neobrutal**
**Nozle**
**Nozle Dark**
## Importing CurrentPlan
```tsx theme={null}
import {
CurrentPlan,
currentPlanMeters,
type BillingSubscription,
type CurrentPlanDetail,
type UsageDashboardFeature,
} from '@nozle-js/react'
```
## Rendering CurrentPlan
Inside a `BillingProvider` with `billingEndpoint`, the card reads the subscription, the plan's limits and this period's usage itself:
```tsx app/settings/billing/page.tsx theme={null}
'use client'
import { BillingProvider } from '@nozle-js/react'
export default function BillingSettings() {
return (
Manage billing} />
)
}
```
The card shows the plan name, a status label, the price and interval, "Changes to \ on \" for a scheduled change, and one meter per metered limit, filled with this period's usage.
## Data
Pass `subscription` (the shape `useSubscription` returns) and `usage` to render your own data:
```tsx theme={null}
const subscription: BillingSubscription = {
subscription: {
external_id: 'sub_123',
plan_code: 'pro',
status: 'active',
ending_at: null,
plan: { code: 'pro', name: 'Pro', amount_cents: 2900, currency: 'USD', interval: 'monthly' },
},
pending_change: { plan_code: 'scale', name: 'Scale', effective_at: '2026-11-01T00:00:00Z' },
past_due: false,
}
const usage: UsageDashboardFeature[] = [{ key: 'api_calls', label: 'API calls', used: 41200, limit: 50000 }]
export function PlanSummary() {
return
}
```
> **Full example data**
>
> ```tsx theme={null}
> const subscription: BillingSubscription = {
> subscription: {
> external_id: 'sub_123',
> plan_code: 'pro',
> status: 'active',
> ending_at: null,
> plan: { code: 'pro', name: 'Pro', amount_cents: 2900, currency: 'USD', interval: 'monthly' },
> },
> pending_change: { plan_code: 'scale', name: 'Scale', effective_at: '2026-11-01T00:00:00Z' },
> past_due: false,
> }
>
> const usage: UsageDashboardFeature[] = [
> { key: 'api_calls', label: 'API calls', used: 41200, limit: 50000 },
> { key: 'seats', label: 'Seats', used: 6, limit: 10 },
> ]
>
> const details: CurrentPlanDetail[] = [
> { label: 'Renews', value: 'Nov 1, 2026' },
> { label: 'AI credits included', value: '500 / month' },
> ]
>
> export function PlanSummary() {
> return (
> subscription={subscription}
> usage={usage}
> details={details}
> actions={Manage billing}
> />
> )
> }
> ```
### Live data
Leave `subscription` out and, inside a `BillingProvider` with `billingEndpoint`, `CurrentPlan` reads:
* the subscription with [`useSubscription`](/sdks/react/hooks#the-hooks),
* the plan's metered limits from the public catalog with `usePlans`,
* this period's units with `useUsage`, joined to the limits by feature code.
Serve `billingEndpoint` with `createBillingHandler` from `@nozle-js/node`; see [Serve the hooks from your backend](/sdks/react/hooks#serve-the-hooks-from-your-backend).
> [!NOTE]
>
> Without `subscription`, `CurrentPlan` needs `BillingProvider` with `billingEndpoint`, or it throws "Billing hooks need BillingProvider billingEndpoint, a backend route served by createBillingHandler".
### Meters from your own data
`currentPlanMeters(entitlements, usage)` joins a plan's metered entitlements with a period's `charges_usage` and returns `usage` rows:
```tsx theme={null}
import { usePlans, useSubscription, useUsage } from '@nozle-js/react'
export function PlanWithMeters() {
const subscription = useSubscription()
const { plans } = usePlans()
const usage = useUsage()
const plan = plans.find((entry) => entry.code === subscription.data?.subscription?.plan_code)
return (
)
}
```
## Examples
### Overdue and ending
`past_due: true` shows `pastDueMessage` as an alert, and `ending_at` turns the label into "Ends \" for a subscription cancelled at the end of its period.
```tsx theme={null}
const subscription: BillingSubscription = {
subscription: {
external_id: 'sub_123',
plan_code: 'pro',
status: 'active',
ending_at: '2026-11-01T00:00:00Z',
plan: { code: 'pro', name: 'Pro', amount_cents: 2900, currency: 'USD', interval: 'monthly' },
},
pending_change: null,
past_due: true,
}
export function PlanSummary() {
return
}
```
### Loading, empty and error
`isLoading` shows a placeholder, `subscription={null}` shows `emptyMessage`, and `error` shows its message as an alert.
```tsx theme={null}
export function PlanStates() {
return (
<>
)
}
```
## API reference
**subscription** `BillingSubscription | null`
The subscription, plan, `ending_at`, scheduled change and `past_due`. `null` shows the empty message. Defaults to the subscription read through `billingEndpoint`.
**usage** `UsageDashboardFeature[]`
One meter per row: `{ key, label, used, limit }`. `limit: null` shows "Unlimited". Each meter is labelled "\