CurrentPlan

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.

CurrentPlan for Pro with a change to Scale scheduled, an 82% notice for API calls, two meters and two detail rows, light theme

Importing CurrentPlan

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:

app/settings/billing/page.tsx

'use client'
import { BillingProvider } from '@nozle-js/react'

export default function BillingSettings() {
  return (
    <BillingProvider publishableKey="pk_nozle_..." billingEndpoint="/api/nozle">
      <CurrentPlan actions={<a href="/settings/billing/portal">Manage billing</a>} />
    </BillingProvider>
  )
}

The card shows the plan name, a status label, the price and interval, “Changes to <plan> on <date>” 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:

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 <CurrentPlan subscription={subscription} usage={usage} />
}

Full example data

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 (
    <CurrentPlan
      subscription={subscription}
      usage={usage}
      details={details}
      actions={<a href="/settings/billing/portal">Manage billing</a>}
    />
  )
}

Live data

Leave subscription out and, inside a BillingProvider with billingEndpoint, CurrentPlan reads:

the subscription with useSubscription,
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.

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:

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 (
    <CurrentPlan
      subscription={subscription.data ?? null}
      usage={currentPlanMeters(plan?.entitlements, usage.data)}
      isLoading={subscription.isPending}
      error={subscription.error}
    />
  )
}

Examples

Overdue and ending

past_due: true shows pastDueMessage as an alert, and ending_at turns the label into “Ends <date>” for a subscription cancelled at the end of its period.

CurrentPlan with the overdue payment alert and the Ends Nov 1, 2026 label, light theme

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 <CurrentPlan subscription={subscription} usage={[]} />
}

Loading, empty and error

isLoading shows a placeholder, subscription={null} shows emptyMessage, and error shows its message as an alert.

CurrentPlan loading placeholder, No active plan message, and an error message, light theme

export function PlanStates() {
  return (
    <>
      <CurrentPlan subscription={null} isLoading />
      <CurrentPlan subscription={null} />
      <CurrentPlan subscription={null} error="Subscription could not be loaded." />
    </>
  )
}

API reference

BillingSubscription | null

The subscription, plan, ending_at, scheduled change and past_due. null shows the empty message. Defaults to the subscription read through billingEndpoint.

UsageDashboardFeature[]

One meter per row: { key, label, used, limit }. limit: null shows “Unlimited”. Each meter is labelled “<label> used this period”. Defaults to the plan’s metered limits joined with this period’s units.

CurrentPlanDetail[]

Extra { label, value } rows under the meters, for example a renewal date. value can be any React node.

ReactNode

Shown on the right of the header, for example a link to the billing portal.

number | null

default:80

A meter at or above this percentage shows “You have used N% of the <label> included in <plan>.” null turns these notices off.

string

Shown as an alert when past_due is true.

string

default:"Current plan"

The header text.

string

default:"No active plan."

Shown when there is no subscription.

boolean

default:false

Shows a loading placeholder.

Error | string | null

default:null

Shows the message as an alert.

string

default:"en-US"

Formats the dates.

Appearance

Theme, variables and element overrides on top of the provider’s. See Appearance.

States

State	What shows
Loading	A loading placeholder.
No subscription	`emptyMessage`, “No active plan.” by default.
Error	The error message as an alert.
`past_due`	`pastDueMessage` as an alert.
Meter at or above `warningPercent`	”You have used N% of the <label> included in <plan>.”

The status label depends on the subscription:

Subscription	Label	Colour
`active`, no `ending_at`	Active	Success
`ending_at` set	Ends <date>	Warning
`pending`	Pending	Warning
`incomplete`	Awaiting payment	Warning
`canceled`	Canceled	Muted
`terminated`	Ended	Muted

Another status is shown as sent. The card shows Powered by Nozle.

Appearance

Element keys

currentPlan (root), currentPlan__name, currentPlan__status, currentPlan__price, currentPlan__scheduled, currentPlan__notice, currentPlan__usage, currentPlan__details. The meters take the UsageMeter elements.Style them with appearance.elements. See Elements.

UsageDashboard

Usage meters on their own.

PlanChangeControl

Lets the customer change the plan.

PlanBadge

The plan name as a small badge.

BillingPortal

Subscriptions, invoices and billing details.

Setup

Components

Billing

Entitlements

Importing CurrentPlan

Rendering CurrentPlan

Data

Live data

Meters from your own data

Examples

Overdue and ending

Loading, empty and error

API reference

States

Appearance

UsageDashboard

PlanChangeControl

PlanBadge

BillingPortal

​Importing CurrentPlan

​Rendering CurrentPlan

​Data

​Live data

​Meters from your own data

​Examples

​Overdue and ending

​Loading, empty and error

​API reference

​States

​Appearance

​Related

UsageDashboard

PlanChangeControl

PlanBadge

BillingPortal

Importing CurrentPlan

Rendering CurrentPlan

Data

Live data

Meters from your own data

Examples

Overdue and ending

Loading, empty and error

API reference

States

Appearance

Related