VGS Collect.js in React: the wrapper's fields first, then the same iframes in a 3D card

If you just want VGS card fields in React, use @vgs/collect-js-react on its own: four field components, free, and you style the text with a css prop. This page is for the other case: the same VGS iframes inside an animated 3D card that shows the brand, flips for the CVC and only lights up Pay when every field is valid.

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 { loadVGSCollect } from "@vgs/collect-js";
import type { IVGSCollect, IVGSCollectForm, VGSCollectFormState } from "@vgs/collect-js-react";
import CardCheckout, { type CardFieldsSlot } from "@/components/CardCheckout";

type Submit = (cardholder: string) => Promise<unknown>;

const vaultId = process.env.NEXT_PUBLIC_VGS_VAULT_ID!;

// Load Collect.js once per page, even when Strict Mode runs effects twice.
// The loader resolves to the global VGSCollect object; the React package ships its type.
let collect: Promise<IVGSCollect> | undefined;
const loadCollect = () =>
  (collect ??= loadVGSCollect({ vaultId, environment: "sandbox", version: "4.0.1" }) as Promise<IVGSCollect>);

// The fields are iframes and don't read Tailwind, so their text is styled here.
const css = {
  color: "#F4F4F6",
  "font-size": "19px",
  "font-family": "ui-monospace, SFMono-Regular, Menlo, monospace",
  "&::placeholder": { color: "#4a4f61" },
};

function VgsFields({ slot, onReady }: { slot: CardFieldsSlot; onReady: (submit: Submit | null) => void }) {
  useEffect(() => {
    let gone = false;
    let form: IVGSCollectForm | undefined;

    // Runs on every keystroke and focus change, with one entry per field.
    const stateCallback = (state: VGSCollectFormState) => {
      if (!state) return;
      const fields = Object.values(state);
      slot.onChange({
        complete: fields.length === 3 && fields.every((f) => f.isValid),
        brand: state.card_number?.cardType ?? null, // "visa", "mastercard", "amex"...
      });
    };

    (async () => {
      const VGSCollect = await loadCollect();
      // Collect.js 4 replaces the deprecated create() with session().
      const f = await VGSCollect.session({ vaultId, env: "sandbox", stateCallback });
      form = f;
      if (gone) return f.unmount();

      f.field("#vgs-number", {
        type: "card-number",
        name: "card_number",
        validations: ["required", "validCardNumber"],
        // Required by the 2.1.1 types. List the brands you take: in our test an empty array rejected every card.
        validCardBrands: [{ type: "visa" }, { type: "mastercard" }, { type: "amex" }],
        placeholder: "1234 5678 9012 3456",
        autoComplete: "cc-number",
        css,
      });
      f.field("#vgs-expiry", {
        type: "card-expiration-date",
        name: "card_exp",
        validations: ["required", "validCardExpirationDate"],
        yearLength: 2,
        placeholder: "MM / YY",
        autoComplete: "cc-exp",
        css,
      });
      const cvc = f.field("#vgs-cvc", {
        type: "card-security-code",
        name: "card_cvc",
        validations: ["required", "validCardSecurityCode"],
        placeholder: "123",
        autoComplete: "cc-csc",
        css,
      });
      cvc.on("focus", () => slot.onChange({ focus: "cvc" })); // flips the card
      cvc.on("blur", () => slot.onChange({ focus: null }));

      // Pay sends the three fields through your vault's inbound route.
      // Your server receives aliases in their place, never the card number.
      onReady(
        (cardholder) =>
          new Promise((resolve, reject) =>
            f.submit(
              "/api/vgs/charge",
              { data: (fields: Record<string, unknown>) => ({ ...fields, cardholder }) },
              (status, data) =>
                typeof status === "number" && status < 300 ? resolve(data) : reject(new Error("That card didn't go through.")),
              () => reject(new Error("Check the card details.")),
            ),
          ),
      );
    })();

    return () => {
      gone = true;
      onReady(null);
      form?.unmount();
    };
  }, [slot, onReady]);

  // Collect.js sizes its iframe from the box it lands in, so let it fill the slot's box.
  const box = `${slot.fieldClassName} [&_iframe]:h-full`;

  return (
    <div className="space-y-3">
      <div>
        <label className={slot.labelClassName}>Card number</label>
        <div id="vgs-number" className={box} />
      </div>
      <div className="flex gap-3">
        <div className="flex-1">
          <label className={slot.labelClassName}>Expiry</label>
          <div id="vgs-expiry" className={box} />
        </div>
        <div className="flex-1">
          <label className={slot.labelClassName}>CVC</label>
          <div id="vgs-cvc" className={box} />
        </div>
      </div>
    </div>
  );
}

// The piece is a fixed 1000 x 660 stage. Scale it down to fit narrow screens.
function useFitScale() {
  const [scale, setScale] = useState(1);
  useEffect(() => {
    const fit = () => setScale(Math.min(1, window.innerWidth / 1000));
    fit();
    window.addEventListener("resize", fit);
    return () => window.removeEventListener("resize", fit);
  }, []);
  return scale;
}

export default function VgsCardCheckout() {
  const router = useRouter();
  const scale = useFitScale();
  const submit = useRef<Submit | null>(null);
  const setSubmit = useRef((s: Submit | null) => (submit.current = s)).current;

  return (
    <div className="overflow-hidden" style={{ height: 660 * scale }}>
      <CardCheckout
        className="origin-top-left"
        style={{ transform: `scale(${scale})` }}
        resetAfter={null}
        renderCardFields={(slot) => <VgsFields slot={slot} onReady={setSubmit} />}
        onConfirm={async ({ name }) => {
          if (!submit.current) throw new Error("The card fields haven't loaded yet.");
          await submit.current(name);
          router.push("/thanks");
        }}
      />
    </div>
  );
}

app/pay/page.tsx

import VgsCardCheckout from "./checkout";

export default function PayPage() {
  return <VgsCardCheckout />;
}

app/api/vgs/charge/route.ts

import { ProxyAgent, fetch } from "undici";

// Server only. Your inbound route forwards the Pay request here, with aliases
// (like "tok_sandbox_...") where the card number, expiry and CVC were.
type AliasedCard = { card_number: string; card_exp: string; card_cvc: string; cardholder: string };

// Your outbound route reveals the aliases on the way to your card processor.
// Username, password and sandbox.pem come from the VGS dashboard.
const vgsOutbound = new ProxyAgent({
  uri: `https://${process.env.VGS_VAULT_ID}.sandbox.verygoodproxy.com:8443`,
  token: `Basic ${Buffer.from(`${process.env.VGS_PROXY_USERNAME}:${process.env.VGS_PROXY_PASSWORD}`).toString("base64")}`,
  requestTls: { ca: process.env.VGS_SANDBOX_PEM }, // VGS re-signs TLS, so trust its certificate
});

export async function POST(req: Request) {
  const card = (await req.json()) as AliasedCard;

  // Your processor's charge endpoint. Map the field names to what it expects.
  const res = await fetch(process.env.PROCESSOR_CHARGE_URL!, {
    method: "POST",
    dispatcher: vgsOutbound,
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.PROCESSOR_SECRET_KEY}` },
    body: JSON.stringify({
      number: card.card_number,
      expiry: card.card_exp,
      cvc: card.card_cvc,
      name: card.cardholder,
    }),
  });

  if (!res.ok) return Response.json({ error: "declined" }, { status: 402 });
  return Response.json({ ok: true });
}

Good to know

What the card can show: the card number, expiry and CVC are typed into VGS iframes, so your page and your server never hold the digits. The 3D card hears when all three fields are valid, when the CVC field has focus, and the brand from Collect.js's form state (cardType). It lights up Pay, flips for the CVC and shows a Visa or Mastercard mark. It doesn't show the number the buyer types.
Why the paid snippet doesn't use VGSCollectSession: in @vgs/collect-js-react 2.1.1 both VGSCollectSession and the older VGSCollectForm render their own <form>, and the card's slot sits inside the piece's own <form> (its Pay button submits it). A form inside a form isn't valid HTML, and React flags it in development. So the snippet calls Collect.js directly: session() for the form, field() into three divs in the slot, and submit() from onConfirm.
validCardBrands: the 2.1.1 types make it required on a card-number field, and VGS's reference lists an empty array as the default. In our test with Collect.js 4.0.1, an empty array marked a valid test Visa as "is not a valid card number", while leaving it out or listing brands worked. So the snippet lists the brands you take: Visa, Mastercard and Amex all validated.
Collect.js 4.0.0 deprecated VGSCollect.create() in favour of VGSCollect.session(), per VGS's reference read October 26, 2026. session() worked with only vaultId, env and stateCallback in our test. The @vgs/collect-js 0.8.0 loader resolves to unknown, so the snippet types it with IVGSCollect from @vgs/collect-js-react. Without a version the loader asks for "canary" and warns you to pin one; the snippet pins 4.0.1, the newest in VGS's changelog today.
What we ran on October 26, 2026: these files type-check and pass next build against @vgs/collect-js-react 2.1.1, @vgs/collect-js 0.8.0, undici 7.30.1, next 15.5.28, react 19.1.1, @types/react 19.3.0, framer-motion 11.18.2 and TypeScript 5.9.3, with the shipped CardCheckout source. Four deliberate mistakes failed the check, as they should. In headless Chromium at 390 and 1440 px, with the public sample sandbox vault from VGS's docs, the three iframes mounted inside the card, VGS's test Visa number showed the Visa mark, focusing the CVC flipped the card, Pay turned on once all three were valid, and the page had no errors and no sideways scroll.
What we didn't run: we have no VGS account, so no inbound or outbound route of our own. Pay against the sample vault was refused by that vault (it has no route for /api/vgs/charge), so we didn't see a full aliased round trip from the browser. VGS's own sample inbound route did swap a test value for a tok_sandbox_ alias when we called it. The server route reached VGS's forward proxy and authenticated with the sample credentials from VGS's docs, and the sample vault's route rules then refused our IP, so no processor call went through. No payment was made.
Set NEXT_PUBLIC_VGS_VAULT_ID (it starts with tnt and is safe in the browser) plus VGS_VAULT_ID, VGS_PROXY_USERNAME, VGS_PROXY_PASSWORD, VGS_SANDBOX_PEM, PROCESSOR_CHARGE_URL and PROCESSOR_SECRET_KEY on the server. In the VGS dashboard, point the inbound route's upstream at your app and add redact filters for card_number, card_exp and card_cvc, and add an outbound route with reveal filters for your processor's host. Switch "sandbox" to "live" in both places when you go live.
Size: the piece is a fixed 1000 x 660 stage, the same as its demo. The snippet scales it to the screen width with a CSS transform, as the README describes. On a phone that makes the card and the fields small, so many stores show it on wider screens and keep VGS's plain fields on phones.
Tailwind v4: text inside the iframes takes its colour, size and font from the css object in the snippet (keys are CSS property names), not from your CSS. Collect.js sizes each iframe from the box it lands in, so the snippet adds [&_iframe]:h-full to the slot's field class. Our CSS leak check of this piece found every rule starts with .qcc-, so it doesn't touch the rest of your styles (re-read October 26, 2026).

When VGS's own fields in the React wrapper are enough

VGS Collect.js puts each card input in an iframe served from VGS. When the form is submitted, the values go through your vault's inbound route, VGS keeps the raw data in its vault and your server receives aliases in its place. VGS's README says the script has to load from its js.verygoodvault.com domain to stay PCI compliant, which is why @vgs/collect-js is a loader and not the library itself.
For most forms the React wrapper is the whole job: @vgs/collect-js-react 2.1.1 (MIT, React 16 to 19 as peers, last published June 2026) gives you CardholderField, CardNumberField, CardExpirationDateField and CardSecurityCodeField. Style the text inside each iframe with the css prop and the box around it with className. vgs-form.tsx below is that route, type-checked and run in a browser on October 26, 2026.
Its README recommends VGSCollectSession for new work and keeps VGSCollectForm for older code. One thing we hit: in 2.1.1 the session needs VGSCollectProvider above it. Without it, the session's setup calls a provider function that isn't there, onErrorCallback gets the error and the fields never mount.
Building for React Native? The web wrapper doesn't apply there. VGS documents a separate React Native SDK.

app/pay/vgs-form.tsx (the free route)

"use client";
import { useEffect, useState } from "react";
import { loadVGSCollect } from "@vgs/collect-js";
import { VGSCollectProvider, VGSCollectSession, type VGSCollectFormState } from "@vgs/collect-js-react";

const { CardholderField, CardNumberField, CardExpirationDateField, CardSecurityCodeField } = VGSCollectSession;

// Your vault id from the VGS dashboard. It starts with "tnt" and is safe in the browser.
const vaultId = process.env.NEXT_PUBLIC_VGS_VAULT_ID!;

// Each field is an iframe, so it can't see your CSS. This object is its stylesheet.
const css = { "font-size": "16px", color: "#111827", "&::placeholder": { color: "#9ca3af" } };
const box = "h-11 rounded-lg border border-gray-300 px-3";

export default function VgsCardForm() {
  const [ready, setReady] = useState(false);
  const [state, setState] = useState<VGSCollectFormState>(null);
  const [result, setResult] = useState("");

  useEffect(() => {
    // Loads Collect.js from js.verygoodvault.com. Pin the version before you go live.
    loadVGSCollect({ vaultId, environment: "sandbox", version: "4.0.1" })
      .then(() => setReady(true))
      .catch(() => setResult("The card form could not load."));
  }, []);

  if (!ready) return <p>{result || "Loading the card form"}</p>;

  const allValid = !!state && Object.values(state).every((field) => field.isValid);

  // In 2.1.1 the session needs VGSCollectProvider above it, or the fields never mount.
  return (
    <VGSCollectProvider>
    <VGSCollectSession
      vaultId={vaultId}
      environment="sandbox"
      // Posts to your vault's inbound route, which swaps the card data for aliases
      // and forwards the request to your server at /api/vgs/charge.
      submit={{ api: "proxy", action: "/api/vgs/charge" }}
      stateCallback={setState}
      onSubmitCallback={(status, data) => setResult(`${status} ${JSON.stringify(data)}`)}
      onErrorCallback={(errors) => setResult(JSON.stringify(errors))}
    >
      <div className="grid max-w-sm gap-3">
        <CardholderField className={box} name="cardholder" validations={["required"]} placeholder="Name on card" css={css} />
        <CardNumberField className={box} name="card_number" validations={["required", "validCardNumber"]} showCardIcon css={css} />
        <CardExpirationDateField className={box} name="card_exp" validations={["required", "validCardExpirationDate"]} yearLength={2} css={css} />
        <CardSecurityCodeField className={box} name="card_cvc" validations={["required", "validCardSecurityCode"]} css={css} />
        <button type="submit" disabled={!allValid} className="h-11 rounded-lg bg-black text-white disabled:opacity-40">
          Pay
        </button>
        {result && <pre className="whitespace-pre-wrap break-all text-xs">{result}</pre>}
      </div>
    </VGSCollectSession>
    </VGSCollectProvider>
  );
}

Collect.js form state and field events in 4.0.1

We read these from VGS's reference and the 2.1.1 type definitions. The state callback gets one object per field, keyed by the field's name, with isValid, isEmpty, isDirty, isFocused, isTouched and errorMessages. A card-number field adds cardType ("visa", "mastercard", "amex" and more), and bin and last4 once the number is valid.
Fields take on() with focus, blur, update, delete, keydown, keypress and keyup. The snippet uses focus and blur on the CVC field to flip the card, and the state callback for everything else.
form.submit(path, options, responseCallback, validationCallback) sends the fields through your inbound route to path on your upstream. options.data can be a function that receives the fields and returns the body, which is how the snippet adds the cardholder name from the card's own input. The status in the response callback is a number, or the string "Network Error", so the snippet checks for a number before reading it.

The server side: aliases in, revealed on the way out

Inbound route: the browser posts to your vault's verygoodproxy.com address, VGS swaps the card values for aliases and forwards the request to your upstream. When we called VGS's public sample route the way its docs show, the account number came back as a tok_sandbox_ alias.
Outbound route: your server sends the aliases to your processor through VGS's forward proxy on port 8443, with the proxy username and password from the dashboard, and VGS puts the real values back on the way out. VGS re-signs that TLS connection, so your server has to trust VGS's sandbox or live certificate. Without it, our test failed with a self-signed certificate error. route.ts above does this with undici's ProxyAgent and requestTls.ca.
Your processor, your rules: the field names, the endpoint and the response all come from whoever charges the card. VGS's guides cover several of them, including a Stripe setup.

"VGS Collect.js script was not loaded"

That message comes from the @vgs/collect-js loader (0.8.0 source, read today). It tries js.verygoodvault.com first and, from Collect.js 2.3.0, js3.verygoodvault.com as a fallback, and rejects with this text when both fail.
Things to check: a Content Security Policy needs those two hosts in script-src, and js.verygoodvault.com in frame-src, because that is where the field iframes load from in our test. Browser extensions that block scripts can do it too. Call the loader in useEffect: on the server it rejects with "window is undefined." instead.

How this differs from the Basis Theory, Airwallex and Adyen card guides

Basis Theory is the closest match on this site: its guide also puts a tokenization vendor's iframes in the same card slot, with React components for each field. With VGS the swap happens on routes: in front of your server on the way in, and in front of your processor on the way out.
Airwallex and Adyen are processors with their own fields, so the payment is confirmed in the browser. With VGS the browser only sends aliases to your server, and your server charges through whichever processor you use.

Install

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

Props

renderCardFields: the three VGS iframes inside the design
onConfirm: form.submit() through your inbound route; throw to show the error
className / style: scale the fixed 1000 x 660 stage to the screen
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: Stripe Elements With a Custom Card Design in React and Next.js

Questions

Does the 3D card see the card number?

No. The number, expiry and CVC stay in VGS's iframes and reach your server as aliases. The card only hears validity, which field has focus, and the brand from Collect.js's form state.

VGSCollectSession or VGSCollectForm?

The 2.1.1 README recommends VGSCollectSession for new integrations and keeps VGSCollectForm for backward compatibility. Wrap the session in VGSCollectProvider, or the fields don't mount.

Why not put VGSCollectSession inside the card's slot?

Both wrapper components render a <form>, and the slot is already inside the card's form. The snippet uses Collect.js's own session() and field() calls instead, the same calls the wrapper makes underneath.

Does @vgs/collect-js-react work with React 19?

Its 2.1.1 peers are React 16, 17, 18 and 19 (npm, read October 26, 2026). Our snippets type-check with @types/react 19.3.0 and ran on react 19.1.1 in a browser.

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.