Chargebee Components in React: hosted checkout first, then card fields in Next.js

If you sell subscriptions with Chargebee and don't need your own card UI, use Chargebee's hosted checkout: one script, one button, no server route. Chargebee's page takes the card and creates the subscription. This page starts there, then builds the other case in Next.js App Router: Chargebee's card fields with @chargebee/chargebee-js-react-wrapper, a typed route that creates the subscription, and the same fields inside an animated checkout whose success screen is a receipt.

One payment$3

By buying you agree to the Terms.

One payment, no subscription
Download right after paying
Use it in client projects
Won't run on the listed stack? We fix it or refund you

Ready forCursorv0Lovableshadcn CLI

Full product pageReact · Tailwind · TypeScript

Start with Chargebee's hosted checkout

lib/chargebee-js.ts (loads Chargebee.js once)

"use client";
// Chargebee.js is a script tag, not an npm module: Chargebee asks you to load it from js.chargebee.com
// and not to host it yourself. These are the calls this page uses, typed by hand.
export type CbFieldState = {
  field?: "number" | "expiry" | "cvv";
  cardType?: string; // "visa", "mastercard"...
  complete: boolean;
  empty: boolean;
  error?: { errorCode?: string; message: string };
};
type CbProduct = object;
export type CbInstance = {
  getCart(): { replaceProduct(product: CbProduct): void; proceedToCheckout(): void };
  initializeProduct(itemPriceId: string, quantity?: number): CbProduct;
};
type CbGlobal = {
  init(options: { site: string; publishableKey?: string; isItemsModel?: boolean }): CbInstance;
};

// init() may run once per page (Chargebee wants tearDown() before a second init), so cache the promise.
let instance: Promise<CbInstance> | undefined;

export function loadChargebee(): Promise<CbInstance> {
  instance ??= new Promise((resolve, reject) => {
    const script = document.createElement("script");
    script.src = "https://js.chargebee.com/v2/chargebee.js";
    script.onload = () => {
      const { Chargebee } = window as unknown as { Chargebee: CbGlobal };
      resolve(
        Chargebee.init({
          site: process.env.NEXT_PUBLIC_CHARGEBEE_SITE!, // "acme-test" for acme-test.chargebee.com
          publishableKey: process.env.NEXT_PUBLIC_CHARGEBEE_PUBLISHABLE_KEY, // needed for the card fields
          isItemsModel: true, // Product Catalog 2.0 (item prices)
        }),
      );
    };
    script.onerror = () => {
      instance = undefined;
      reject(new Error("Chargebee.js didn't load"));
    };
    document.head.append(script);
  });
  return instance;
}

components/subscribe-button.tsx (the hosted checkout, no server route)

"use client";
import { useState } from "react";
import { loadChargebee } from "@/lib/chargebee-js";

// The free route: Chargebee's hosted checkout. No card UI of yours, no server route.
export function SubscribeButton({ itemPriceId }: { itemPriceId: string }) {
  const [busy, setBusy] = useState(false);

  async function open() {
    setBusy(true);
    try {
      const chargebee = await loadChargebee();
      const cart = chargebee.getCart();
      cart.replaceProduct(chargebee.initializeProduct(itemPriceId));
      cart.proceedToCheckout(); // Chargebee's checkout opens over your page
    } finally {
      setBusy(false);
    }
  }

  return (
    <button type="button" onClick={open} disabled={busy} className="rounded-lg bg-zinc-900 px-5 py-3 font-medium text-white disabled:opacity-60">
      {busy ? "Opening checkout..." : "Subscribe"}
    </button>
  );
}

Good to know

Chargebee.js is a script, not an npm module. Chargebee's setup page says to load https://js.chargebee.com/v2/chargebee.js from its servers for PCI compliance, not from your own. loadChargebee() adds the script once, calls Chargebee.init() once and caches the instance, because Chargebee asks you to call tearDown() before a second init().
Init has to happen before CardComponent mounts. In 0.6.9 the wrapper's CardComponent calls Chargebee.getInstance() and load("components") itself when it mounts, and Provider renders nothing until it gets a valid instance. So both snippets render the fields only after loadChargebee() resolves.
The wrapper's event props are typed as React's ChangeEventHandler and FocusEventHandler in 0.6.9, but Chargebee calls them with its own field state: field, cardType, complete, empty and error. The snippets take the event as unknown and read it through the small CbFieldState type, which follows Chargebee's Card Components reference.
Install note: the wrapper's types import from @chargebee/chargebee-js-types, which it lists as a devDependency, so npm i @chargebee/chargebee-js-react-wrapper doesn't bring it. With skipLibCheck on (the Next.js default) styles, placeholder and cbInstance are loosely typed; component names, event prop names and the ref's tokenize() are still checked. A misspelled onChnage and a call to tokenizeCard() both failed our type-check.
The token from tokenize() goes to your server as token_id on customer.create. Chargebee's API docs describe token_id as the payment token generated by Chargebee.js, and its Card Components reference says the token expires 30 minutes after it's made. The route then calls subscription.createWithItems for that customer.
The browser names the plan, the server decides. PLANS in the route is the list of item price ids this page may sell; anything else gets a 400 before Chargebee is called. Prices come from your Chargebee catalog, not from the request.
3D Secure: tokenize() doesn't run a 3DS challenge. If your gateway or your buyers' banks need one (common for European cards), create a payment intent on the server and call authorizeWith3ds() on the same card ref, which 0.6.9 exposes, then pass the payment intent to the subscription call. Or let the hosted checkout handle it.

Chargebee Components with the React wrapper

When the card fields have to live in your own form, Chargebee's React wrapper gives you Provider, CardComponent, CardNumber, CardExpiry and CardCVV (the exports of @chargebee/chargebee-js-react-wrapper 0.6.9). Nesting the three field components inside CardComponent is what Chargebee calls Fields mode: each field is its own iframe, so you lay them out and style the boxes around them.
The iframes can't read your CSS. Text colour, size and placeholder colour go in the styles object; borders and padding go on the wrapper divs, here with Tailwind classes.
On submit, the card ref's tokenize() sends the card to your gateway through Chargebee and returns a temporary token. Your route turns that token into a customer and a subscription. Card digits never reach your page code or your server.
Card Components needs a publishable key in Chargebee.init() and a gateway that Chargebee lists as supported for Card Components. Both come from your Chargebee site settings.

components/chargebee-card-form.tsx (Chargebee Components, Fields mode)

"use client";
import { useEffect, useRef, useState, type ComponentRef, type FormEvent } from "react";
import { CardComponent, CardCVV, CardExpiry, CardNumber, Provider } from "@chargebee/chargebee-js-react-wrapper";
import { loadChargebee, type CbFieldState, type CbInstance } from "@/lib/chargebee-js";

type Field = "number" | "expiry" | "cvv";

// The fields are iframes and can't read your CSS, so their text is styled here. Borders go on the wrappers.
const styles = {
  base: { color: "#18181b", fontSize: "16px", fontFamily: "system-ui, sans-serif", "::placeholder": { color: "#a1a1aa" } },
  invalid: { color: "#dc2626" },
};
const box = "rounded-md border border-zinc-300 px-3 py-3 focus-within:border-zinc-900";

export function ChargebeeCardForm({ itemPriceId }: { itemPriceId: string }) {
  const [chargebee, setChargebee] = useState<CbInstance>();
  const card = useRef<ComponentRef<typeof CardComponent>>(null);
  const [done, setDone] = useState<Record<Field, boolean>>({ number: false, expiry: false, cvv: false });
  const [error, setError] = useState<string>();
  const [busy, setBusy] = useState(false);
  const [subscribed, setSubscribed] = useState(false);

  // Chargebee.init() has to run before CardComponent mounts: the wrapper calls Chargebee.getInstance() itself.
  useEffect(() => {
    loadChargebee().then(setChargebee, (e: Error) => setError(e.message));
  }, []);

  // The wrapper types this as a React ChangeEvent; Chargebee actually passes its field state.
  const onField = (e: unknown) => {
    const state = e as CbFieldState;
    if (state.field) setDone((d) => ({ ...d, [state.field!]: state.complete }));
    setError(state.error?.message);
  };

  async function onSubmit(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const form = new FormData(e.currentTarget);
    setBusy(true);
    setError(undefined);
    try {
      const firstName = String(form.get("name") ?? "");
      const { token } = (await card.current!.tokenize({ firstName })) as { token: string };
      const res = await fetch("/api/subscribe", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ token, firstName, email: form.get("email"), itemPriceId }),
      });
      const data = (await res.json()) as { error?: string };
      if (!res.ok) throw new Error(data.error);
      setSubscribed(true);
    } catch (err) {
      setError((err as Error).message || "Couldn't subscribe. Try again.");
    } finally {
      setBusy(false);
    }
  }

  if (subscribed) return <p className="font-medium">You're subscribed. Check your inbox for the receipt.</p>;
  if (!chargebee) return error ? <p className="text-sm text-red-600">{error}</p> : <div className="h-52 animate-pulse rounded-md bg-zinc-100" />;

  return (
    <form onSubmit={onSubmit} className="grid gap-3">
      <input name="email" type="email" required placeholder="Email" autoComplete="email" className="rounded-md border border-zinc-300 px-3 py-3" />
      <input name="name" required placeholder="Name on card" autoComplete="cc-name" className="rounded-md border border-zinc-300 px-3 py-3" />
      <Provider cbInstance={chargebee}>
        <CardComponent ref={card} styles={styles} locale="en" placeholder={{ number: "Card number", expiry: "MM / YY", cvv: "CVC" }} className="grid gap-3">
          <CardNumber className={box} onChange={onField} />
          <div className="grid grid-cols-2 gap-3">
            <CardExpiry className={box} onChange={onField} />
            <CardCVV className={box} onChange={onField} />
          </div>
        </CardComponent>
      </Provider>
      {error && <p className="text-sm text-red-600">{error}</p>}
      <button type="submit" disabled={busy || !(done.number && done.expiry && done.cvv)} className="rounded-lg bg-zinc-900 px-5 py-3 font-medium text-white disabled:opacity-50">
        {busy ? "Subscribing..." : "Subscribe"}
      </button>
    </form>
  );
}

app/api/subscribe/route.ts (creates the customer and the subscription)

import Chargebee from "chargebee";
import { NextResponse } from "next/server";

const chargebee = new Chargebee({
  site: process.env.CHARGEBEE_SITE!,
  apiKey: process.env.CHARGEBEE_API_KEY!, // secret API key: server only, never NEXT_PUBLIC
});

// The plans this page sells. The browser names one; the server decides whether that's allowed.
const PLANS = new Set(["pro-USD-monthly", "pro-USD-yearly"]);

type Body = { token?: string; email?: string; firstName?: string; itemPriceId?: string };

export async function POST(req: Request) {
  const { token, email, firstName, itemPriceId } = (await req.json()) as Body;
  if (!token || !email || !itemPriceId || !PLANS.has(itemPriceId)) {
    return NextResponse.json({ error: "Missing card, email or plan." }, { status: 400 });
  }

  try {
    // token_id is the Chargebee.js token: it becomes the customer's card. It expires 30 minutes after tokenize().
    const { customer, card } = await chargebee.customer.create({ email, first_name: firstName, token_id: token });
    const { subscription } = await chargebee.subscription.createWithItems(customer.id, {
      subscription_items: [{ item_price_id: itemPriceId }],
    });
    return NextResponse.json({ subscriptionId: subscription.id, status: subscription.status, last4: card?.last4 });
  } catch (err) {
    const message = (err as { message?: string }).message ?? "Chargebee didn't accept the card.";
    return NextResponse.json({ error: message }, { status: 402 });
  }
}

Put the Chargebee fields in Receipt Morph Checkout

With the form above, a successful subscription ends on a line of text. Receipt Morph Checkout is our paid piece for making that moment the thing the buyer sees: the card lifts, splits and unrolls into a paper receipt stamped PAID.
Its renderCardFields slot takes your provider's hosted fields, so the three Chargebee iframes sit in its own field boxes (slot.fieldClassName) and card digits never reach the component. Chargebee's change events tell it when all three fields are complete, the number field's cardType puts the VISA mark on the card, and focus on the CVC flips the card over.
onConfirm runs when the buyer presses Pay with complete fields. It tokenizes, calls the same /api/subscribe route and returns ok with the last4 from Chargebee's card object, which the receipt prints. If tokenize() or the route fails, the card drops back with the message instead of spinning.
The receipt prints the order you pass: give it the plan as one line item from your server. Two things to change for a subscription: the order summary's row of shipping, returns and warranty notes is fixed text in OrderSummary, and orderId is whatever reference you pass in, since Chargebee's subscription id only exists after Pay. Receipt Morph isn't a shadcn component; you copy its files from the zip.

components/chargebee-receipt-checkout.tsx (Receipt Morph Checkout)

"use client";
import { useEffect, useRef, useState, type ComponentRef, type RefObject } from "react";
import { CardComponent, CardCVV, CardExpiry, CardNumber, Provider } from "@chargebee/chargebee-js-react-wrapper";
import { CheckoutReceiptMorph, type CardFieldsSlot } from "@/components/CheckoutReceiptMorph";
import type { NorthwindData } from "@/data/northwind";
import { loadChargebee, type CbFieldState, type CbInstance } from "@/lib/chargebee-js";

type Order = NorthwindData["store"];
type CardRef = RefObject<ComponentRef<typeof CardComponent> | null>;
type Field = "number" | "expiry" | "cvv";

// Light text for Receipt Morph's dark field boxes. The boxes themselves come from slot.fieldClassName.
const styles = { base: { color: "#f4f4f6", fontSize: "17px", "::placeholder": { color: "#646b80" } }, invalid: { color: "#ff6a3d" } };

function ChargebeeFields({ slot, card }: { slot: CardFieldsSlot; card: CardRef }) {
  const done = useRef<Record<Field, boolean>>({ number: false, expiry: false, cvv: false });

  // Typed as a React ChangeEvent by the wrapper; Chargebee passes its field state.
  const onField = (e: unknown) => {
    const state = e as CbFieldState;
    if (!state.field) return;
    done.current[state.field] = state.complete;
    slot.onChange({
      complete: done.current.number && done.current.expiry && done.current.cvv,
      ...(state.field === "number" ? { brand: state.cardType ?? null } : {}), // "visa" shows the VISA mark
    });
  };
  const focus = (f: "num" | "exp" | "cvc") => () => slot.onChange({ focus: f }); // "cvc" flips the card
  const blur = () => slot.onChange({ focus: null });

  return (
    <CardComponent ref={card} styles={styles} placeholder={{ number: "1234 1234 1234 1234", expiry: "MM / YY", cvv: "CVC" }} className="grid gap-3">
      <div className={slot.fieldClassName}>
        <CardNumber onChange={onField} onFocus={focus("num")} onBlur={blur} />
      </div>
      <div className="grid grid-cols-2 gap-3">
        <div className={slot.fieldClassName}>
          <CardExpiry onChange={onField} onFocus={focus("exp")} onBlur={blur} />
        </div>
        <div className={slot.fieldClassName}>
          <CardCVV onChange={onField} onFocus={focus("cvc")} onBlur={blur} />
        </div>
      </div>
    </CardComponent>
  );
}

// order: the plan as Receipt Morph should print it, built on the server from your item price.
export function ChargebeeReceiptCheckout({ order, itemPriceId, email }: { order: Order; itemPriceId: string; email: string }) {
  const [chargebee, setChargebee] = useState<CbInstance>();
  const card = useRef<ComponentRef<typeof CardComponent>>(null);

  useEffect(() => {
    loadChargebee().then(setChargebee, () => {});
  }, []);

  return (
    <CheckoutReceiptMorph
      order={order}
      autoplayDemo={false}
      renderCardFields={(slot) =>
        chargebee ? (
          <Provider cbInstance={chargebee}>
            <ChargebeeFields slot={slot} card={card} />
          </Provider>
        ) : (
          <div className={slot.fieldClassName} />
        )
      }
      onConfirm={async ({ name }) => {
        if (!card.current) return { ok: false, message: "The card fields are still loading." };
        // tokenize() sends the card to your gateway through Chargebee. A rejection lands back on the card as its message.
        const { token } = (await card.current.tokenize({ firstName: name })) as { token: string };
        const res = await fetch("/api/subscribe", {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({ token, email, firstName: name, itemPriceId }),
        });
        const data = (await res.json()) as { error?: string; last4?: string };
        return res.ok ? { ok: true, last4: data.last4 } : { ok: false, message: data.error };
      }}
    />
  );
}

app/subscribe/page.tsx

import { ChargebeeReceiptCheckout } from "@/components/chargebee-receipt-checkout";
import { getPlanOrder, getSignedInUser } from "@/lib/account";

export default async function SubscribePage() {
  const user = await getSignedInUser();
  // Your lookup: the plan's name, price and tax, as the receipt should print them.
  const order = await getPlanOrder("pro-USD-monthly");
  return <ChargebeeReceiptCheckout order={order} itemPriceId="pro-USD-monthly" email={user.email} />;
}

Card Components or Payment Components

Read this before you start a new integration. Chargebee's Card Components reference, read on October 26, 2026, marks Card Components deprecated: it still works and existing integrations are unaffected, but Chargebee recommends Payment Components for new ones.
The React wrapper on this page (0.6.9, published October 2025) wraps Card Components. Payment Components is created from chargebee.components() in Chargebee.js, renders a full payment form with several methods, runs 3D Secure inside confirm() and works with a payment intent (its create() example passes one in). We found no React wrapper for it among Chargebee's npm packages today, so you mount it into a div yourself.
Payment Components has no per-field change events like the ones Receipt Morph's card listens to; you call validate() and then confirm(). That's why this page pairs the animated card with Card Components. If you want only cards and a custom card UI, Card Components still does the job; if you want wallets and bank methods next to cards, use Payment Components or the hosted checkout.

What we ran on October 26, 2026

Versions read from the npm registry that day: @chargebee/chargebee-js-react-wrapper 0.6.9 (published October 10, 2025, MIT, peers React 17, 18 or 19) and chargebee 3.34.0 (published September 24, 2026, Node 18 or newer). Chargebee.js setup, Card Components, Payment Components and the hosted checkout calls are from Chargebee's docs read the same day; token_id is from Chargebee's Create a customer API docs.
All six files type-check with TypeScript 5.9.3 strict and build with next build on Next.js 15.5.28, React 19.1.1 and framer-motion 11.18.2, with the shipped Receipt Morph Checkout source. Five deliberate mistakes failed the type-check, as they should: tokenizeCard() on the card ref, an onChnage prop on CardNumber, item_price instead of item_price_id, token instead of token_id, and a cvv focus value the slot doesn't accept.
In headless Chromium at 390 and 1440 px, with a made-up site name: chargebee.js loaded from js.chargebee.com without an account and mounted all three field iframes in Receipt Morph's boxes. Typing Chargebee's test number 4111 1111 1111 1111 put the VISA mark on the card, the CVC field flipped it, and Pay with all three fields complete called tokenize(), which Chargebee rejected because the site doesn't exist; the card dropped back and showed that message. No sideways scroll at either width.
What we didn't run: we have no Chargebee account, so no token was issued, no customer or subscription was created and nothing was charged. The route reached Chargebee's API and got its site-not-found error back as a 402, and returned 400 for a missing token or a plan outside PLANS. The hosted checkout button did open Chargebee's checkout frame, at the site's chargebee.com address under /hosted_pages/checkout with the item price id in the URL, with 0 page errors; with a made-up site there is no checkout behind it. Run all of it on a Chargebee test site with a test gateway before you ship.

Install

Copy from the zipPut react/src/components + react/src/data into src/, then npm i framer-motion chargebee @chargebee/chargebee-js-react-wrapper.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

order: the plan as the receipt prints it (items, total)
renderCardFields: slot for Chargebee's CardNumber, CardExpiry and CardCVV; card digits never reach the component
onConfirm: tokenize, create the subscription on your server, return ok and last4
onComplete: gets the receipt: orderId, total, last4, paidAt
autoplayDemo: false in a real app
accent / secondary: brand colours

How qodesign compares

qodesign vs 21st.dev21st.dev is best for: browsing a huge marketplace and copying many components a month.
qodesign vs Skiper UISkiper UI is best for: unusual interaction details for landing pages: image reveals, cursor trails, tooltips, drag-and-scroll galleries.

All comparisons, with prices read on each library's own site.

From the blog: Stripe Elements With a Custom Card Design in React and Next.js

Questions

Does Chargebee have a React component library?

Chargebee publishes @chargebee/chargebee-js-react-wrapper, which wraps Card Components: Provider, CardComponent, CardNumber, CardExpiry and CardCVV. Version 0.6.9 lists React 17, 18 and 19 as peers. Chargebee.js itself still loads as a script tag.

Do I need a server for Chargebee Components?

Yes, for the subscription. The browser only gets a temporary token from tokenize(); your server sends it as token_id with your secret API key, which must never reach the browser. The hosted checkout is the route with no server code.

Why does CardComponent render nothing?

Usually Chargebee.init() hasn't run yet, or Provider got no instance. The wrapper calls Chargebee.getInstance() when CardComponent mounts, so load the script and init first, as loadChargebee() does, and render the fields after it resolves.

Is Chargebee Card Components deprecated?

Chargebee's reference marks it deprecated as of October 2026: it still works and existing integrations are unaffected, and new integrations are pointed to Payment Components. See the section above for what that means for a custom card UI.

Is Receipt Morph Checkout a shadcn component?

No. You copy its files from the zip into your project.

Does Receipt Morph Checkout work in Next.js?

Yes, as a client component. Keep "use client" at the top of the file that renders it, as in the snippet above. App Router and Pages Router both work.

Can Cursor or v0 add it for me?

Yes. Each download has a PROMPT.md. Paste it into Cursor, Lovable, v0 or Claude Code and it fits the piece into your app.

Can I use it in client work?

Yes, in personal and client projects. You can't resell the code itself as a kit.