Braintree Hosted Fields in React: Drop-in first, then styled fields in a 3D card

If you want cards, PayPal and Venmo in one box, use Braintree's own Drop-in UI: it's free in braintree-web-drop-in and it is the least code. If you only want card fields that look like your product, use Hosted Fields from braintree-web, with no wrapper. This page does both in the Next.js App Router, covers styling and validation, then puts Hosted Fields inside an animated 3D card that shows the brand and flips for the CVV.

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

Use it in Next.js

app/pay/checkout.tsx

"use client";
import { useEffect, useRef, useState } from "react";
import { useRouter } from "next/navigation";
import { client, hostedFields, type HostedFields, type HostedFieldsEvent } from "braintree-web";
import CardCheckout, { type CardFieldsSlot } from "@/components/CardCheckout";
import { charge } from "./actions";

// Hosted Fields style the input inside each iframe, and only these CSS properties
// (color, font, letter-spacing, line-height, padding, opacity, transition and a few more).
// Borders, background and height belong to your own wrapper div.
const styles = {
  input: { color: "#F4F4F6", "font-size": "19px", "font-family": "ui-monospace, monospace" },
  "::placeholder": { color: "#4a4f61" },
  ".invalid": { color: "#FF5C6C" },
};

// One card left in e.cards means Braintree knows the brand. The 3D card draws Visa and Mastercard.
const brandOf = (e: HostedFieldsEvent) => {
  const type = e.cards.length === 1 ? e.cards[0].type : null;
  return type === "master-card" ? "mastercard" : type;
};
const focusOf = { number: "number", expirationDate: "expiry", cvv: "cvc" } as const;
const allValid = (e: HostedFieldsEvent) =>
  e.fields.number.isValid && e.fields.expirationDate.isValid && e.fields.cvv.isValid;

function BraintreeFields({ slot, authorization, onReady }: {
  slot: CardFieldsSlot;
  authorization: string;
  onReady: (hf: HostedFields | null) => void;
}) {
  const number = useRef<HTMLDivElement>(null);
  const expiry = useRef<HTMLDivElement>(null);
  const cvv = useRef<HTMLDivElement>(null);
  const [failed, setFailed] = useState(false);

  useEffect(() => {
    let gone = false;
    let hf: HostedFields | undefined;

    (async () => {
      try {
        const bt = await client.create({ authorization });
        // Strict Mode runs this effect twice in dev. The first run is cleaned up before
        // client.create resolves, so it stops here and never adds a second set of iframes.
        if (gone) return;
        const created = await hostedFields.create({
          client: bt,
          styles,
          fields: {
            number: { container: number.current!, placeholder: "4111 1111 1111 1111" },
            expirationDate: { container: expiry.current!, placeholder: "MM/YY" },
            cvv: { container: cvv.current!, placeholder: "123" },
          },
        });
        if (gone) return void created.teardown();
        hf = created;
        hf.on("cardTypeChange", (e) => slot.onChange({ brand: brandOf(e) }));
        hf.on("validityChange", (e) => slot.onChange({ complete: allValid(e) }));
        hf.on("focus", (e) => {
          const f = e.emittedBy;
          slot.onChange({ focus: f === "number" || f === "expirationDate" || f === "cvv" ? focusOf[f] : null });
        });
        hf.on("blur", () => slot.onChange({ focus: null }));
        onReady(hf);
      } catch {
        if (!gone) setFailed(true);
      }
    })();

    return () => {
      gone = true;
      onReady(null);
      void hf?.teardown();
    };
  }, [authorization, slot, onReady]);

  // Braintree adds braintree-hosted-fields-invalid to the wrapper, so the border can turn red.
  const box = `${slot.fieldClassName} [&.braintree-hosted-fields-invalid]:border-[#FF5C6C]`;
  return (
    <div className="grid gap-[15px]">
      <div>
        <label className={slot.labelClassName}>Card number</label>
        <div ref={number} className={box} />
      </div>
      <div className="flex gap-[14px]">
        <div className="flex-1">
          <label className={slot.labelClassName}>Expiry</label>
          <div ref={expiry} className={box} />
        </div>
        <div className="flex-1">
          <label className={slot.labelClassName}>CVV</label>
          <div ref={cvv} className={box} />
        </div>
      </div>
      {failed && <p role="alert" className="text-sm text-[#FF5C6C]">The card fields didn't load. Refresh to try again.</p>}
    </div>
  );
}

// The checkout is a fixed 1000 x 660 scene. Scale it down to the width you give it, as the README says.
function useFit() {
  const box = useRef<HTMLDivElement>(null);
  const [scale, setScale] = useState(1);
  useEffect(() => {
    const ro = new ResizeObserver(([entry]) => setScale(Math.min(1, entry.contentRect.width / 1000)));
    ro.observe(box.current!);
    return () => ro.disconnect();
  }, []);
  return { box, scale };
}

export default function BraintreeCheckout({ authorization, amount }: { authorization: string; amount: number }) {
  const router = useRouter();
  const { box, scale } = useFit();
  const fields = useRef<HostedFields | null>(null);
  const setFields = useRef((hf: HostedFields | null) => (fields.current = hf)).current;

  return (
    <div ref={box} className="w-full max-w-[1000px] overflow-hidden" style={{ height: 660 * scale }}>
    <CardCheckout
      className="origin-top-left"
      style={{ transform: `scale(${scale})` }}
      amount={amount}
      currency="USD"
      resetAfter={null}
      renderCardFields={(slot) => <BraintreeFields slot={slot} authorization={authorization} onReady={setFields} />}
      onConfirm={async ({ name }) => {
        if (!fields.current) throw new Error("The card fields haven't loaded yet.");
        // tokenize() turns the iframes' contents into a one-time nonce. No card digits reach your code.
        const { nonce } = await fields.current.tokenize({ cardholderName: name });
        const result = await charge(nonce);
        if (!result.ok) throw new Error(result.error);
        setTimeout(() => router.push(`/thanks?tx=${result.id}`), 1200); // let the success state play
      }}
    />
    </div>
  );
}

app/pay/page.tsx

import { gateway } from "@/lib/braintree";
import BraintreeCheckout from "./checkout";

export const dynamic = "force-dynamic";

export default async function PayPage() {
  // A fresh client token for each visit. It authorizes the browser, it can't charge anything.
  const { clientToken } = await gateway().clientToken.generate({});
  return <BraintreeCheckout authorization={clientToken} amount={10} />;
}

app/pay/actions.ts

"use server";
import { gateway } from "@/lib/braintree";

type Charge = { ok: true; id: string } | { ok: false; error: string };

export async function charge(nonce: string): Promise<Charge> {
  // The amount is set here on the server, never by the browser.
  const result = await gateway().transaction.sale({
    amount: "10.00",
    paymentMethodNonce: nonce,
    options: { submitForSettlement: true },
  });
  if (result.success) return { ok: true, id: result.transaction.id };
  // result.message holds the processor's or the validation error's text.
  return { ok: false, error: result.message || "That card didn't go through." };
}

lib/braintree.ts

import braintree from "braintree";

// Server only. The private key never reaches the browser.
// Built on first use: the constructor throws when a key is missing, and next build loads
// this module while it collects page data, often before your keys exist.
let instance: braintree.BraintreeGateway | undefined;

export function gateway() {
  return (instance ??= new braintree.BraintreeGateway({
    environment: process.env.BRAINTREE_ENV === "production" ? braintree.Environment.Production : braintree.Environment.Sandbox,
    merchantId: process.env.BRAINTREE_MERCHANT_ID!,
    publicKey: process.env.BRAINTREE_PUBLIC_KEY!,
    privateKey: process.env.BRAINTREE_PRIVATE_KEY!,
  }));
}

Good to know

What the card can show: the number, expiry and CVV sit in Braintree's iframes, so your page and your server never see the digits. tokenize() hands you a one-time nonce and your server charges it. The 3D card hears the brand from cardTypeChange, the valid state from validityChange, and which field has focus. It shows a Visa or Mastercard mark, lights up Pay and flips for the CVV. It doesn't show the number the buyer types.
What we ran on October 26, 2026: we type-checked every file on this page against braintree-web 3.147.0 (types from @types/braintree-web 3.143.2, because braintree-web ships no type files), braintree 3.41.0 (types from @types/braintree 3.4.5), braintree-web-drop-in 1.48.0 (types from @types/braintree-web-drop-in 1.39.4), next 15.5.28, react 19.1.1, @types/react 19.3.0, framer-motion 14.6.0 and TypeScript 5.9.3, with the shipped CardCheckout source. Five deliberate mistakes failed the check, as they should, and next build passed. In Chromium at 390 and 1440 px, with the real braintree-web and a made-up key, client.create refused the key, the slot showed its message, and the page had no errors and no sideways scroll. With braintree-web swapped for a local stand-in that fires the same events, the card showed the Mastercard mark, flipped on CVV focus, lit up Pay and passed the nonce to the server action. Under React Strict Mode the fields were created once.
What we didn't run: we have no Braintree sandbox account on this test, so no client token was generated, no real Hosted Fields iframe rendered inside the card's field boxes, and no tokenize(), transaction.sale or 3D Secure check went through. Pay with Braintree's sandbox test cards before you ship.
One build trap we hit: new braintree.BraintreeGateway() throws Missing publicKey when a key is empty, and next build loads your server modules while it collects page data. Our first build of this page failed exactly like that. So lib/braintree.ts creates the gateway on first call, and the build passes before your keys exist.
Strict Mode: in development React runs the effect twice. braintree-web 3.147.0 refuses to put a second set of fields into a container that already has one (HOSTED_FIELDS_FIELD_DUPLICATE_IFRAME, in its source). The snippet checks gone after client.create, so the first run stops before it adds any iframes, and the cleanup calls teardown() on the real one.
submitForSettlement: true asks Braintree to settle the charge right away. Without it the transaction is only authorized and you settle it later. Treat result.success on the server as the answer, and fulfil orders from the transaction or Braintree's webhooks, not from the redirect to /thanks. If your account needs 3D Secure, braintree-web has a separate threeDSecure module whose verifyCard() runs on the nonce before the sale. Its dataCollector module gives you deviceData for the sale if you use Braintree's fraud tools.
Size: the checkout is a fixed 1000 x 660 scene, and its README says to scale it with a CSS transform. The snippet scales it to the width of its parent, so a 390 px phone shows it at about 0.39 and the fields are small. For a phone-first checkout, the plain Hosted Fields form below is the better fit.
Set BRAINTREE_MERCHANT_ID, BRAINTREE_PUBLIC_KEY and BRAINTREE_PRIVATE_KEY, and BRAINTREE_ENV=production when you go live. All three stay on the server. The card draws a Visa or a Mastercard mark; other brands still pay with no logo. Braintree spells the type master-card, so the snippet maps it to mastercard. Every rule in the piece's card-checkout.css starts with .qcc- (re-read October 26, 2026), so it doesn't touch the rest of your styles.

Braintree Drop-in or Hosted Fields: start with Drop-in

Braintree gives you two ways to take a card on your own page, both free with your account. Drop-in UI (braintree-web-drop-in) is a finished payment box: card fields, plus PayPal, Venmo, Apple Pay and Google Pay when you turn them on. Hosted Fields (the hosted-fields module of braintree-web) are single iframes per field that you lay out and style yourself.
Drop-in fits most stores better. It's one dropin.create() and one requestPaymentMethod(), and Braintree handles the layout, the errors and the PayPal flow. drop-in.tsx below is the whole Drop-in route, and it sends the nonce to the same server action as the rest of this page.
Hosted Fields are for when the form has to look like your product. You give each field a container, style the text inside it, and draw the borders, focus rings and error states on your own divs. That is the route the rest of this page takes.
One packaging fact read today: braintree-web-drop-in 1.48.0 pins braintree-web 3.123.2 as its own dependency, so a page that uses both Drop-in and braintree-web 3.147.0 ships two copies of braintree-web. Pick one per page.

app/pay/drop-in.tsx (the free route)

"use client";
import { useEffect, useRef, useState } from "react";
import dropin, { type Dropin } from "braintree-web-drop-in";
import { charge } from "./actions";

// The free route: Braintree's Drop-in UI. Cards, plus PayPal and Venmo when your account has them.
export default function BraintreeDropIn({ authorization }: { authorization: string }) {
  const box = useRef<HTMLDivElement>(null);
  const instance = useRef<Dropin | null>(null);
  const [ready, setReady] = useState(false);
  const [error, setError] = useState("");

  useEffect(() => {
    let gone = false;
    dropin
      .create({ authorization, container: box.current!, paypal: { flow: "checkout", amount: "10.00", currency: "USD" } })
      .then((d) => {
        if (gone) return void d.teardown();
        instance.current = d;
        setReady(true);
      })
      .catch(() => !gone && setError("The payment form didn't load."));
    return () => {
      gone = true;
      void instance.current?.teardown();
      instance.current = null;
    };
  }, [authorization]);

  async function pay() {
    try {
      const { nonce } = await instance.current!.requestPaymentMethod();
      const result = await charge(nonce);
      if (result.ok) location.assign("/thanks");
      else setError(result.error);
    } catch {
      setError("Check the card details and try again.");
    }
  }

  return (
    <div className="max-w-md">
      <div ref={box} />
      <button disabled={!ready} onClick={pay} className="mt-4 w-full rounded-lg bg-black px-4 py-3 text-white disabled:opacity-50">
        Pay
      </button>
      {error && <p role="alert" className="mt-2 text-sm text-red-600">{error}</p>}
    </div>
  );
}

Braintree Hosted Fields in Next.js App Router, no wrapper

braintree-web renders into plain divs, so it works in a client component on React 19 without a React wrapper. You need three things: a client token from your server, client.create() with it in the browser, and hostedFields.create() with a container for each field.
The server half is the braintree package (3.41.0). gateway.clientToken.generate({}) returns the token, and app/pay/page.tsx above passes it down as a prop, so there's no extra fetch. After tokenize(), the server action calls gateway.transaction.sale with the nonce and an amount the browser never sets.
hosted-fields.tsx below is the plain version: three fields, a Pay button that waits for all three to be valid, and an error under each field. It is free to copy and has nothing from qodesign in it.
Still on react-braintree-fields? Its latest release is 2.0.0 from February 19, 2023, and its peer range is React 16 to 18 (npm registry, read October 26, 2026). The PayPal Card Fields guide maps its components to the braintree-web calls used here.

app/pay/hosted-fields.tsx (plain Hosted Fields, free)

"use client";
import { useEffect, useRef, useState } from "react";
import { client, hostedFields, type HostedFields } from "braintree-web";
import { charge } from "./actions";

type Name = "number" | "expirationDate" | "cvv";
const messages: Record<Name, string> = {
  number: "Enter a valid card number.",
  expirationDate: "Enter a valid expiry date.",
  cvv: "Enter the 3 or 4 digit code.",
};

// Plain Hosted Fields, no animation: three styled iframes and a Pay button.
export default function HostedFieldsForm({ authorization }: { authorization: string }) {
  const hf = useRef<HostedFields | null>(null);
  const [ready, setReady] = useState(false);
  const [valid, setValid] = useState(false);
  const [brand, setBrand] = useState("");
  const [errors, setErrors] = useState<Partial<Record<Name, string>>>({});
  const [busy, setBusy] = useState(false);

  useEffect(() => {
    let gone = false;
    let instance: HostedFields | undefined;
    (async () => {
      const bt = await client.create({ authorization });
      if (gone) return;
      instance = await hostedFields.create({
        client: bt,
        styles: {
          input: { "font-size": "16px", "font-family": "system-ui, sans-serif", color: "#111827" },
          ":focus": { color: "#111827" },
          ".invalid": { color: "#dc2626" },
          "::placeholder": { color: "#9ca3af" },
        },
        fields: {
          number: { container: "#card-number", placeholder: "4111 1111 1111 1111" },
          expirationDate: { container: "#card-expiry", placeholder: "MM/YY" },
          cvv: { container: "#card-cvv", placeholder: "123" },
        },
      });
      if (gone) return void instance.teardown();
      hf.current = instance;
      setReady(true);

      instance.on("validityChange", (e) => {
        // Only complain once the value can't become valid by typing more.
        const name = e.emittedBy;
        if (name === "number" || name === "expirationDate" || name === "cvv") {
          const msg = e.fields[name].isPotentiallyValid ? undefined : messages[name];
          setErrors((old) => ({ ...old, [name]: msg }));
        }
        setValid(e.fields.number.isValid && e.fields.expirationDate.isValid && e.fields.cvv.isValid);
      });
      // On blur, a field that has something in it but isn't valid gets its message.
      instance.on("blur", (e) => {
        const name = e.emittedBy;
        const f = e.fields[name];
        if ((name === "number" || name === "expirationDate" || name === "cvv") && !f.isEmpty && !f.isValid) {
          setErrors((old) => ({ ...old, [name]: messages[name] }));
        }
      });
      instance.on("cardTypeChange", (e) => {
        setBrand(e.cards.length === 1 ? e.cards[0].niceType : "");
        // American Express uses a 4 digit code, so the CVV placeholder follows the brand.
        if (e.cards.length === 1) void instance?.setPlaceholder("cvv", e.cards[0].code.size === 4 ? "1234" : "123");
      });
    })().catch(() => !gone && setErrors({ number: "The card form didn't load. Refresh to try again." }));

    return () => {
      gone = true;
      hf.current = null;
      void instance?.teardown();
    };
  }, [authorization]);

  async function onSubmit(event: React.FormEvent) {
    event.preventDefault();
    if (!hf.current) return;
    setBusy(true);
    try {
      const { nonce } = await hf.current.tokenize();
      const result = await charge(nonce);
      if (result.ok) location.assign("/thanks");
      else setErrors({ number: result.error });
    } catch (err) {
      // HOSTED_FIELDS_FIELDS_EMPTY or HOSTED_FIELDS_FIELDS_INVALID, with the field names in details.
      const keys = (err as { details?: { invalidFieldKeys?: string[] } }).details?.invalidFieldKeys ?? ["number", "expirationDate", "cvv"];
      setErrors(Object.fromEntries(keys.filter((k): k is Name => k in messages).map((k) => [k, messages[k]])));
    } finally {
      setBusy(false);
    }
  }

  const box = "h-11 rounded-md border border-gray-300 px-3 [&.braintree-hosted-fields-focused]:border-black [&.braintree-hosted-fields-invalid]:border-red-600";
  return (
    <form onSubmit={onSubmit} className="grid max-w-sm gap-3">
      <label htmlFor="card-number" className="text-sm">Card number {brand && <span className="text-gray-500">({brand})</span>}</label>
      <div id="card-number" className={box} />
      {errors.number && <p className="text-sm text-red-600">{errors.number}</p>}
      <div className="grid grid-cols-2 gap-3">
        <div>
          <label htmlFor="card-expiry" className="text-sm">Expiry</label>
          <div id="card-expiry" className={box} />
          {errors.expirationDate && <p className="text-sm text-red-600">{errors.expirationDate}</p>}
        </div>
        <div>
          <label htmlFor="card-cvv" className="text-sm">CVV</label>
          <div id="card-cvv" className={box} />
          {errors.cvv && <p className="text-sm text-red-600">{errors.cvv}</p>}
        </div>
      </div>
      <button disabled={!ready || !valid || busy} className="mt-2 rounded-md bg-black px-4 py-2.5 text-white disabled:opacity-40">
        {busy ? "Paying…" : "Pay"}
      </button>
    </form>
  );
}

Braintree Hosted Fields styling: what the styles object takes

The styles object is CSS for the input inside each iframe, keyed by selector: input, :focus, .valid, .invalid, ::placeholder, a field class such as .number or .cvv, and @media queries. braintree-web 3.147.0 keeps only these properties: color, font and its parts (font-family, font-size, font-weight, font-style, font-variant and its parts, font-stretch, font-size-adjust), letter-spacing, line-height, text-align, text-shadow, direction, opacity, outline, margin, padding, box-shadow, appearance, transition and a few -webkit- and -moz- prefixed versions.
Background, border, height and width are not on the list. Braintree's own docs say it plainly: "Any other CSS should be specified on your page and outside of any Braintree configuration. Trying to set unsupported properties will fail and put a warning in the console." So the box around each field is your div, and that's where Tailwind goes.
Braintree adds classes to your container div as the buyer types: braintree-hosted-fields-focused, braintree-hosted-fields-valid and braintree-hosted-fields-invalid. With Tailwind v4 an arbitrary variant styles them, for example [&.braintree-hosted-fields-invalid]:border-red-600, as both snippets do.
Two quieter rules from the stylesheet code it uses (inject-stylesheet 7.1.0): a value that contains a slash, a semicolon, url or a backslash is dropped, so font: 16px/24px Inter doesn't apply; set font-size and line-height separately. And instead of an object you can pass a class name from your own CSS as a string; Braintree reads that class's computed styles, keeping the allowed properties only.

Braintree Hosted Fields validation

Every event hands you the state of all fields. Each field has isEmpty, isFocused, isValid and isPotentiallyValid. isPotentiallyValid stays true while the value could still become valid by typing more, so it's the one to use while the buyer types; check isValid on blur.
validityChange fires when a field turns valid or invalid. The plain snippet shows a message once a field can't become valid, adds one on blur when a filled field isn't valid, and enables Pay only when number, expiry and CVV are all valid. cardTypeChange gives you the brand and the card's code size, so the CVV placeholder can switch to four digits for American Express.
tokenize() checks again. It rejects with HOSTED_FIELDS_FIELDS_EMPTY or HOSTED_FIELDS_FIELDS_INVALID, and err.details.invalidFieldKeys names the fields, which the snippet turns into messages. A card that passes in the browser can still be declined: then transaction.sale returns success false and result.message says why.
To accept only some brands, pass supportedCardBrands on the number field, for example { "american-express": false }. braintree-web 3.147.0 marks the older rejectUnsupportedCards option as deprecated since 3.46.0.

How Hosted Fields events drive the 3D card

Credit Card Checkout V1 has a renderCardFields slot. Inside it you render the containers and call slot.onChange with what the provider tells you; the card does the rest. The main snippet wires it like this:
cardTypeChange: when exactly one card type is left, its type becomes the brand (master-card becomes mastercard), and the card shows the Visa or Mastercard mark. validityChange: complete is true when number, expirationDate and cvv are all valid, which lights up Pay once the name is filled. focus: emittedBy number, expirationDate or cvv becomes focus number, expiry or cvc, and cvc flips the card. blur sets focus back to null.
When Pay is pressed, onConfirm gets the cardholder name from the card, passes it to tokenize({ cardholderName }), and sends the nonce to the server action. Throw from onConfirm and the card shows your message and goes back to idle.

Install

Copy from the zipPut react/src/components into src/, then npm i framer-motion braintree-web braintree && npm i -D @types/braintree-web @types/braintree.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

renderCardFields: Braintree Hosted Fields inside the design
onConfirm: tokenize() and charge on your server; throw to show the error
amount / currency: what the card shows (your server sets what Braintree charges)
className / style: the scale transform for the fixed 1000 x 660 scene
resetAfter: null keeps the success state

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: Credit Card Input in React: Spacing, Brand and Luhn

Questions

Does the 3D card see the card number?

No. The number, expiry and CVV stay in Braintree's iframes. The card only hears the brand, whether the fields are valid, and which field has focus.

Hosted Fields or Drop-in?

Drop-in for most stores: one prebuilt box with cards, PayPal and Venmo. Hosted Fields when the card form has to match your design, as on this page.

Why doesn't my border or background style apply?

Hosted Fields only take text styles inside the iframe, such as color, font and padding. Put borders, backgrounds and height on your own container div, and style its braintree-hosted-fields-focused and -invalid classes.

Does braintree-web work with React 19 and Next.js?

Yes, in a client component. It mounts iframes into the divs you give it and has no React peer dependency. Our snippets type-check and build with react 19.1.1 and next 15.5.28. We didn't run them against a Braintree sandbox account.

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.