Appearance

Every component takes its look from appearance. Set it once on BillingProvider for all components inside, or on one component. No Tailwind or extra CSS is needed. Requires @nozle-js/react 0.11.0. You can also pick the look in the dashboard and save it for your organization: every component then uses it without any code. See Saved appearance.

Themes

The default. You get it without any appearance.

PricingTable, CreditBalance and UsageDashboard in the light theme

import { BillingProvider } from '@nozle-js/react'
import { light } from '@nozle-js/react/themes'

<BillingProvider publishableKey="pk_..." appearance={{ theme: light }}>

Dark surfaces. Put the components on a dark page background.

import { BillingProvider } from '@nozle-js/react'
import { dark } from '@nozle-js/react/themes'

<BillingProvider publishableKey="pk_..." appearance={{ theme: dark }}>

The Nozle dashboard look: flat panels with fine borders, pill buttons, and a hard ink shadow on the primary button only. Plan cards use the panel layout.

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

<BillingProvider publishableKey="pk_..." appearance={{ theme: nozle }}>

The theme uses the Nunito and JetBrains Mono fonts, which your app loads, for example with next/font/google or a Google Fonts <link>. Without them the system fonts are used.

The dark version of nozle. Put the components on a dark page background.

import { BillingProvider } from '@nozle-js/react'
import { nozleDark } from '@nozle-js/react/themes'

<BillingProvider publishableKey="pk_..." appearance={{ theme: nozleDark }}>

The theme uses the Nunito and JetBrains Mono fonts, which your app loads, for example with next/font/google or a Google Fonts <link>. Without them the system fonts are used.

Flat: no shadows, small corners, a near-black primary.

import { BillingProvider } from '@nozle-js/react'
import { minimal } from '@nozle-js/react/themes'

<BillingProvider publishableKey="pk_..." appearance={{ theme: minimal }}>

Thick borders, square corners and a hard offset shadow.

import { BillingProvider } from '@nozle-js/react'
import { neobrutal } from '@nozle-js/react/themes'

<BillingProvider publishableKey="pk_..." appearance={{ theme: neobrutal }}>

Every colour, the font, corner radius, border width and shadow can be changed on top of a theme with variables (full list below):

<BillingProvider
  publishableKey="pk_..."
  appearance={{ theme: dark, variables: { colorPrimary: '#7c3aed', borderRadius: '8px' } }}
>

Saved appearance

Requires @nozle-js/react 0.13.0. In the dashboard, open Developers > Customize SDK, pick a theme, colours and plan card options, and select Save changes. Nozle saves the appearance for your organization, next to the plan card content. Every SDK component in your app picks it up automatically, with no code. The components read it from the plan catalog request they already make (meta.sdk_appearance in GET /api/v1/plans), with your publishable key. The page has two tabs:

Global settings are saved at the root of the SDK and apply to every component: theme, “Powered by Nozle”, button, surface, text and status colours, and radius. The tab also shows the BillingProvider code to paste at the root of your app if you prefer to set the same appearance in code. It has no preview, because it is not tied to one component.
Component settings change one component only. Pick a component in the Component dropdown to see it as it would look in your app, with live data from your organization where available and sample data otherwise. The panel lists only the settings that component reads (a usage meter has an accent colour but no buttons), and the plan card layout and the highlighted plan appear on the pricing table and plan card. A field left empty follows the global settings, and the placeholder shows the global value. A field you set is marked Set here. Use global removes the component’s own settings.

Save changes saves the content, the global settings and the component settings together.

What is saved

Setting	Values
Theme	`light`, `dark`, `nozle`, `nozleDark`, `minimal`, `neobrutal`
Colours	`colorPrimary`, `colorPrimaryForeground`, `colorBackground`, `colorCard`, `colorForeground`, `colorMuted`, `colorMutedForeground`, `colorAccent`, `colorAccentForeground`, `colorBorder`, `colorDanger`, `colorWarning`, `colorSuccess`, `colorSecondary`, `colorInput`, `colorHighlight`, `colorHighlightForeground`, `buttonBorderColor`. Hex only: `#rgb` or `#rrggbb`.
Shape	`borderRadius`, `buttonRadius`, `borderWidth`, `buttonBorderWidth`. Lengths such as `12px` or `1rem`.
Plan cards	`planCardLayout` (`card` or `panel`), set per component
Pricing table	`highlightStyle` (`outline` or `filled`; the dashboard shows Outlined and Contained), `annualDiscountLabel` (up to 40 characters), `showToggle`, set per component
Branding	`hideBranding`, only for plans that remove the “Powered by Nozle” line. It hides the line in the SDK components and the customer portal, not on invoice, credit note or receipt PDFs.
Components	`components.<Name>` with its own `theme`, `variables`, `planCardLayout` and `pricingTable`. Names: `PricingTable`, `PlanCard`, `PlanComparison`, `PlanBadge`, `CurrentPlan`, `PlanChangeControl`, `CancellationControl`, `UsageMeter`, `UsageDashboard`, `UsageAlert`, `UsageBreakdown`, `UsageTrend`, `CreditBalance`, `CreditHistory`, `PaymentMethodDisplay`, `CheckoutButton`, `UpgradeButton`, `UpgradeModal`, `UpgradePrompt`, `LockedOverlay`

Fonts, shadows, elements, enterpriseEmail and any CSS are not saved. Set them in code. The saved object is at most 8 KB. Anything outside this list, or a value in the wrong format, is rejected with 422.

Precedence

From lowest to highest: the saved global appearance, the appearance saved for that component, appearance on BillingProvider, appearance on the component in code. A component rendered inside another, such as a UsageMeter in a UsageDashboard, uses its own saved settings. A theme set in code replaces the values that theme defines; saved values the code theme does not define stay. For example, you saved the nozle theme and a colorHighlight of #16a34a. In code you set the minimal theme:

<BillingProvider publishableKey="pk_..." appearance={{ theme: minimal }}>

The primary colour becomes minimal’s, and the highlight colour stays #16a34a, because minimal does not define it.

Turn it off

<BillingProvider publishableKey="pk_..." savedAppearance={false}>

With savedAppearance={false}, the components ignore the saved appearance and use only your code. Without a saved appearance, nothing is applied, and --nozle-* CSS variables you set on :root keep working. Components that only show data, such as UsageMeter, make one cached request for the plan catalog through the provider. A page with several components makes one request per BillingProvider.

Highlighted plan

highlightPlan on PricingTable marks one plan: its border and its button take the highlight colour (colorHighlight, by default the primary colour), with the label from highlightLabel (default “Most Popular”; null for none). highlightStyle picks how the card stands out. The tabs follow the theme you picked above:

Outline (default):

PricingTable in the light theme with the Pro card outlined

Filled:

With filled, the card takes the highlight colour, and its text and button switch to the highlight text colour.

import { PricingTable } from '@nozle-js/react'

<PricingTable highlightPlan="pro" />
<PricingTable highlightPlan="pro" highlightStyle="filled" />

The style, the colours and the toggle can also be saved in the dashboard: see Saved appearance. A highlightStyle prop wins over the saved one. Set the colours with colorHighlight and colorHighlightForeground; they default to the primary colours. Change the badge text with highlightLabel, or pass highlightLabel={null} for no badge.

<PricingTable
  highlightPlan="pro"
  highlightStyle="filled"
  highlightLabel="Best value"
  appearance={{ variables: { colorHighlight: '#16a34a', colorHighlightForeground: '#ffffff' } }}
/>

Plan card layout

A theme’s planCardLayout picks how PricingTable and PlanCard lay out each plan:

card (default): name, description, price and ticked features. See Plan buttons for which plan gets which button.
panel: the name in a header band, with ACTIVE on the right for the current plan and the highlight label for the highlighted plan, then price, description and plain feature lines. nozle and nozleDark use it.

appearance={{ theme: light, planCardLayout: 'panel' }}

The layout can be saved in the dashboard too: see Saved appearance.

Plan buttons

Requires @nozle-js/react 0.13.0. Which button a plan gets depends on the customer’s plan:

No current plan known: every paid plan gets the primary button. In the nozle, nozleDark and neobrutal themes it has the hard shadow of the theme’s button shadow; light, dark and minimal have none. The highlighted plan keeps its highlight colours.
With currentPlanCode: plans above it get the primary button. The current plan uses the primary colour with no shadow (in the panel layout it also shows the ACTIVE label in the header). Plans at or below it get a plain button.
Contact-sales plans stay outlined.

Combine themes

minimal and neobrutal set shape; light and dark set colour. nozle and nozleDark set both, so use them on their own. Pass several themes in an array. Later ones win where they overlap.

appearance={{ theme: [neobrutal, dark] }}

One component

A component’s own appearance goes on top of the provider’s:

import { CreditBalance } from '@nozle-js/react'

<BillingProvider publishableKey="pk_..." appearance={{ theme: dark }}>
  <PricingTable appearance={{ variables: { colorPrimary: '#16a34a' } }} />
  <CreditBalance balance={balance} />
</BillingProvider>

The order, highest first: the component’s variables, the component’s theme, the provider’s variables, the provider’s theme, the saved appearance, --nozle-* CSS variables set by your app, then the light values.

Text

All text in the components uses one of eight roles. Each role is a CSS font shorthand (weight, size, line height and family) plus a colour. Change a role and every element in it changes, in every component. Every component sets the body role on its root, so no text takes its size, font or colour from your page.

Role	Variable	Default	Colour	What it styles	`nozle` and `nozleDark`
Title	`fontTitle`	`700 20px/1.25`	text	The billing portal title, dialog titles	`900 20px/1.15`
Heading	`fontHeading`	`600 16px/1.35`	text	Plan names, the `CurrentPlan` header and plan name, the credit balance name, portal section and card headings	`900 14px/1.25`
Metric	`fontMetric`	`700 28px/1.1`, numbers font, tabular figures	text	Plan prices, the credit balance, portal prices, balances and usage totals	`800 24px/1` in Nunito
Body	`fontBody`	`400 14px/1.5`	text	Features, table cells, meter labels and values, notices, errors and other sentences	`400 13px/1.5`
Secondary	`fontBody`	as body	muted	Descriptions, plan prices in `CurrentPlan`, card number, empty messages, the usage period	as body
Meta	`fontMeta`	`400 12px/1.4`	muted	Price intervals, “As of” dates, chart labels, card expiry, detail labels, the portal footer	`400 11.5px/1.4`
Label	`labelFont`	`600 12px/1.4`	muted	Table headers, plan card badges, status pills, `PlanBadge`, the portal status badge	`800 10.5px/1.4` JetBrains Mono, uppercase
Action	`fontAction`	`600 14px/1.4`	the button’s colour	Buttons, links, the billing toggle	`800 14px/1.4`

The defaults are in fontFamily; the metric default is in fontFamilyNumbers when it is set. neobrutal sets title and heading to weight 800. The other themes keep the defaults. labelTextTransform and labelLetterSpacing apply with the label role.

appearance={{
  variables: {
    fontHeading: '700 18px/1.3 Inter, sans-serif',
    fontMetric: '600 32px/1 Inter, sans-serif',
  },
}}

Muted text follows colorForeground: when colorMutedForeground is not set, it is colorForeground mixed 62% into colorCard, so a new text colour also recolours descriptions, dates, labels and table headers. Set colorMutedForeground to choose it yourself. Error, warning and success text is the status colour mixed with colorForeground, so it stays readable on its tinted background.

Variables

Variable	CSS variable	Light	Dark
`colorPrimary`	`--nozle-primary`	`#4f46e5`	`#818cf8`
`colorPrimaryForeground`	`--nozle-primary-foreground`	`#ffffff`	`#0b1020`
`colorBackground`	`--nozle-background`	`#ffffff`	`#0b0f19`
`colorCard`	`--nozle-card`	`#ffffff`	`#111827`
`colorForeground`	`--nozle-foreground`	`#111827`	`#f3f4f6`
`colorMuted`	`--nozle-muted`	`#f3f4f6`	`#1f2937`
`colorMutedForeground`	`--nozle-muted-foreground`	`colorForeground` mixed 62% into `colorCard`	same
`colorAccent`	`--nozle-accent`	`#eef2ff`	`#1e1b4b`
`colorAccentForeground`	`--nozle-accent-foreground`	`#3730a3`	`#c7d2fe`
`colorBorder`	`--nozle-border`	`#e5e7eb`	`#374151`
`colorDanger`	`--nozle-destructive`	`#dc2626`	`#f87171`
`colorWarning`	`--nozle-warning`	`#d97706`	`#fbbf24`
`colorSuccess`	`--nozle-success`	`#16a34a`	`#4ade80`
`colorSecondary`	`--nozle-secondary`	`colorMuted`	`colorMuted`
`colorInput`	`--nozle-input`	`colorBorder`	`colorBorder`
`colorHighlight`	`--nozle-highlight`	`colorPrimary`	`colorPrimary`
`colorHighlightForeground`	`--nozle-highlight-foreground`	`colorPrimaryForeground`	`colorPrimaryForeground`
`fontFamily`	`--nozle-font`	system UI font	same
`fontFamilyNumbers`	`--nozle-font-numbers`	the surrounding font	same
`labelFont`	`--nozle-label-font`	`600 12px/1.4` in `fontFamily`	same
`labelTextTransform`	`--nozle-label-transform`	`none`	same
`labelLetterSpacing`	`--nozle-label-spacing`	`normal`	same
`fontTitle`	`--nozle-font-title`	`700 20px/1.25` in `fontFamily`	same
`fontHeading`	`--nozle-font-heading`	`600 16px/1.35` in `fontFamily`	same
`fontMetric`	`--nozle-font-metric`	`700 28px/1.1` in `fontFamilyNumbers`, else `fontFamily`	same
`fontBody`	`--nozle-font-body`	`400 14px/1.5` in `fontFamily`	same
`fontMeta`	`--nozle-font-meta`	`400 12px/1.4` in `fontFamily`	same
`fontAction`	`--nozle-font-action`	`600 14px/1.4` in `fontFamily`	same
`borderRadius`	`--nozle-radius`	`12px`	same
`borderWidth`	`--nozle-border-width`	`1px`	same
`shadow`	`--nozle-shadow`	soft shadow	darker shadow
`buttonRadius`	`--nozle-button-radius`	a fraction of `borderRadius`	same
`buttonBorderWidth`	`--nozle-button-border-width`	`borderWidth`	same
`buttonBorderColor`	`--nozle-button-border`	the primary button’s fill	same
`buttonShadow`	`--nozle-button-shadow`	none	none
`colorScheme`	`color-scheme`	`light`	`dark`

buttonBorderColor and buttonShadow apply to primary buttons only, so one action per view stands out. Secondary buttons take colorSecondary as their fill and colorInput as their border. The font* and label* variables are the text roles described in Text. Numbers in tables are right-aligned in tabular figures, in fontFamilyNumbers. In code, any CSS value works, including var(...) and oklch(...). The saved appearance takes hex colours and simple lengths only, and none of the font, shadow or colorScheme variables. Warning and error tints are mixed from colorWarning and colorDanger. You can also set the CSS variables yourself, for example on :root. A component without appearance reads them. The older --nozle-portal-* and --nozle-pricing-* names still work after the --nozle-* name.

Elements

elements changes one part of a component. A string adds a class name; an object adds inline styles. Every part also has a fixed class, nozle-<key>, for your own CSS.

<PricingTable
  appearance={{
    elements: {
      planCard: 'rounded-none',
      planCard__cta: { textTransform: 'uppercase', letterSpacing: '0.04em' },
    },
  }}
/>

The components style themselves with inline styles, so a class name from elements cannot override a property they set. Use an object for those properties, or a variable.

Component	Keys
`PricingTable`	`pricingTable`, `pricingTable__toggle`, `pricingTable__toggleButton`, `pricingTable__grid`, and the `planCard` keys
`PlanCard`	`planCard`, `planCard__header`, `planCard__badge`, `planCard__name`, `planCard__description`, `planCard__price`, `planCard__features`, `planCard__feature`, `planCard__cta`
`PlanComparison`	`planComparison`, `planComparison__table`, `planComparison__row`, `planComparison__cell`
`CreditBalance`, `CreditHistory`	`creditBalance`, `creditBalance__amount`, `creditHistory`, `creditHistory__table`, `creditHistory__row`
`UsageMeter`, `UsageDashboard`, `UsageAlert`	`usageMeter`, `usageMeter__label`, `usageMeter__value`, `usageMeter__track`, `usageMeter__fill`, `usageDashboard`, `usageAlert`, `usageAlert__dismiss`
`UsageBreakdown`, `UsageTrend`	`usageBreakdown`, `usageBreakdown__row`, `usageTrend`, `usageTrend__bar`
Buttons and checkout	`checkoutButton`, `upgradeButton`, `checkout`, `checkout__submit`, `checkout__error`, `upgradeModal`, `upgradeModal__dialog`, `upgradeModal__actions`
Gates and badges	`upgradePrompt`, `lockedOverlay`, `lockedOverlay__panel`, `planBadge`, `paymentMethod`
`CurrentPlan`	`currentPlan`, `currentPlan__name`, `currentPlan__status`, `currentPlan__price`, `currentPlan__scheduled`, `currentPlan__notice`, `currentPlan__usage`, `currentPlan__details`
`BillingPortal`	`billingPortal`, `billingPortal__section`, `billingPortal__card`, `billingPortal__table`, `billingPortal__error`, `cancellationControl`, `planChangeControl`
`PoweredByNozle`	`poweredBy`

Stripe checkout

Checkout passes the theme’s resolved colours, corner radius and font to Stripe’s Payment Element, and picks Stripe’s night theme on a dark card. Stripe’s embedded Checkout page (a cs_ client secret) uses the branding set in your Stripe dashboard instead.

Upgrading from 0.10

@tanstack/react-query 5 or later is a required peer dependency. Install it with npm install @tanstack/react-query.
PlanCard takes a catalog plan with isCurrent, returnUrl, onSelect and an optional features list, instead of id, name, monthlyPrice, annualPrice, description, isAnnual and children. The Plan type export is removed.
PlanComparison takes catalog plans and optional features rows keyed by plan code, not id.
Components no longer read shadcn’s --primary and --border on their own. To follow a shadcn/ui theme, pass its variables: variables: { colorPrimary: 'var(--primary)', colorPrimaryForeground: 'var(--primary-foreground)', colorCard: 'var(--card)', colorForeground: 'var(--foreground)', colorBorder: 'var(--border)', borderRadius: 'var(--radius)' } (Tailwind v3: wrap each in hsl()).
Without a theme, the default primary is now #4f46e5 everywhere; the portal’s green is gone. Set colorPrimary to keep your colour.
The nozlePreset Tailwind export is deprecated and does nothing for current components.
PricingTable no longer treats a plan as “Custom” because its name contains “enterprise” or “custom”. List those plan codes in contactSalesPlans.

Setup

Components

Billing

Entitlements

Themes

Saved appearance

What is saved

Precedence

Turn it off

Highlighted plan

Plan card layout

Plan buttons

Combine themes

One component

Text

Variables

Elements

Stripe checkout

Upgrading from 0.10

​Themes

​Saved appearance

​What is saved

​Precedence

​Turn it off

​Highlighted plan

​Plan card layout

​Plan buttons

​Combine themes

​One component

​Text

​Variables

​Elements

​Stripe checkout

​Upgrading from 0.10

Themes

Saved appearance

What is saved

Precedence

Turn it off

Highlighted plan

Plan card layout

Plan buttons

Combine themes

One component

Text

Variables

Elements

Stripe checkout

Upgrading from 0.10