Stripe Address Element in React and Next.js: shipping and billing addresses next to a card form

For a shipping or billing address in a Stripe checkout, use AddressElement from @stripe/react-stripe-js. It's free, and the first section below has a whole Next.js file with the Payment Element. This page also builds the case Stripe's Address Element guide doesn't show: the address next to split card fields, where you read it yourself and send it to the PaymentIntent, here above an animated 3D card that shows the brand and flips for the CVC.

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, type ReactNode } from "react";
import { useRouter } from "next/navigation";
import { loadStripe, type Appearance, type StripeAddressElementOptions } from "@stripe/stripe-js";
import { Elements, AddressElement, CardNumberElement, CardExpiryElement, CardCvcElement, useStripe, useElements } from "@stripe/react-stripe-js";
import CardCheckout, { type CardFieldsSlot } from "@/components/CardCheckout";
import { createPaymentIntent } from "./actions";
import { plan } from "./plan";

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);
const mapsKey = process.env.NEXT_PUBLIC_GOOGLE_MAPS_KEY;

// The Address Element follows the Appearance API. Dark inputs to sit next to the card.
const appearance: Appearance = {
  theme: "night",
  variables: { colorBackground: "#12111F", colorText: "#F4F4F6", borderRadius: "12px", fontSizeBase: "15px" },
  rules: {
    ".Label": { color: "#8A8FA3", fontSize: "13px" },
    ".Input": { border: "1px solid #262A36", boxShadow: "none" },
    ".Input:focus": { border: "1px solid #C6FF3D", boxShadow: "0 0 0 3px rgba(198, 255, 61, 0.2)" },
  },
};
// The split card fields don't read appearance. They take the older style option.
const cardStyle = { base: { color: "#F4F4F6", fontFamily: "JetBrains Mono, monospace", fontSize: "18px", "::placeholder": { color: "#6E6A8A" } } };

const addressOptions: StripeAddressElementOptions = {
  mode: "shipping",
  allowedCountries: ["US", "CA", "GB", "DE", "FR"], // keep in sync with SHIP_TO in actions.ts
  fields: { phone: "always" },
  validation: { phone: { required: "never" } },
  // Stripe's own Maps key only covers the Payment Element (or a Link session), not split card fields.
  autocomplete: mapsKey ? { mode: "google_maps_api", apiKey: mapsKey } : { mode: "disabled" },
};

// The checkout piece draws on a fixed 1000 x 660 stage. This scales it to the column on phones.
function Fit({ children }: { children: ReactNode }) {
  const ref = useRef<HTMLDivElement>(null);
  const [scale, setScale] = useState(1);
  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const ro = new ResizeObserver(([entry]) => setScale(Math.min(1, entry.contentRect.width / 1000)));
    ro.observe(el);
    return () => ro.disconnect();
  }, []);
  return (
    <div ref={ref} className="w-full min-w-0 overflow-hidden" style={{ height: 660 * scale }}>
      <div style={{ width: 1000, height: 660, transform: `scale(${scale})`, transformOrigin: "0 0" }}>{children}</div>
    </div>
  );
}

function PayForm() {
  const stripe = useStripe();
  const elements = useElements();
  const router = useRouter();
  const done = useRef({ number: false, expiry: false, cvc: false }).current;
  const [addressError, setAddressError] = useState<string | null>(null);

  const cardFields = (slot: CardFieldsSlot) => {
    const track = (k: keyof typeof done) => (e: { complete: boolean; brand?: string }) => {
      done[k] = e.complete;
      slot.onChange({ complete: done.number && done.expiry && done.cvc, ...(e.brand ? { brand: e.brand } : {}) });
    };
    return (
      <div className="grid gap-[15px]">
        <div>
          <label className={slot.labelClassName}>Card number</label>
          <div className={slot.fieldClassName}><CardNumberElement options={{ style: cardStyle }} onChange={track("number")} /></div>
        </div>
        <div className="flex gap-[14px]">
          <div className="flex-1">
            <label className={slot.labelClassName}>Expiry</label>
            <div className={slot.fieldClassName}><CardExpiryElement options={{ style: cardStyle }} onChange={track("expiry")} /></div>
          </div>
          <div className="flex-1">
            <label className={slot.labelClassName}>CVC</label>
            <div className={slot.fieldClassName}>
              <CardCvcElement
                options={{ style: cardStyle }}
                onChange={track("cvc")}
                onFocus={() => slot.onChange({ focus: "cvc" })} // flips the card
                onBlur={() => slot.onChange({ focus: null })}
              />
            </div>
          </div>
        </div>
      </div>
    );
  };

  return (
    <div className="mx-auto grid w-full max-w-[1000px] gap-6">
      {/* The checkout piece has no address area, so the Address Element sits above it in the same <Elements>. */}
      <section className="rounded-[20px] border border-[#262A36] bg-[#12111F] p-5">
        <h2 className="m-0 mb-4 text-[16px] font-semibold text-[#F4F4F6]">Shipping address</h2>
        <AddressElement
          options={addressOptions}
          // A wrong key or a blocked script ends here. Without a handler Stripe.js only logs it.
          onLoadError={({ error }) => setAddressError(error.message ?? "The address form couldn't load.")}
        />
        {addressError && <p role="alert" className="m-0 mt-3 text-[14px] text-[#FF5C6C]">{addressError}</p>}
      </section>
      <Fit>
        <CardCheckout
          amount={plan.amount / 100}
          currency="USD"
          productName={plan.name}
          resetAfter={null}
          renderCardFields={cardFields}
          // Pay was pressed and Stripe says the three card fields are complete.
          onConfirm={async ({ name }) => {
            if (!stripe || !elements) throw new Error("Stripe hasn't loaded yet.");
            const address = elements.getElement(AddressElement);
            const card = elements.getElement(CardNumberElement);
            if (!address || !card) throw new Error("Checkout fields missing.");
            // getValue() also marks incomplete fields inside the Address Element.
            const { complete, value } = await address.getValue();
            if (!complete) throw new Error("Add a complete shipping address first.");
            const res = await createPaymentIntent(value);
            if ("error" in res) throw new Error(res.error);
            const { error, paymentIntent } = await stripe.confirmCardPayment(res.clientSecret, {
              payment_method: { card, billing_details: { name } }, // the name typed on the card
            });
            if (error) throw error; // the card shows Stripe's message and Pay comes back
            setTimeout(() => router.push(`/thanks?pi=${paymentIntent.id}`), 1200);
          }}
        />
      </Fit>
    </div>
  );
}

export default function Checkout() {
  // Deferred mode: no PaymentIntent yet, so Elements gets the amount and currency up front.
  return (
    <Elements stripe={stripePromise} options={{ mode: "payment", amount: plan.amount, currency: plan.currency, appearance }}>
      <PayForm />
    </Elements>
  );
}

app/pay/actions.ts

"use server";
import Stripe from "stripe";
import type { StripeAddressElementChangeEvent } from "@stripe/stripe-js";
import { plan } from "./plan";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Same countries as allowedCountries in the browser. The browser can be edited, so check again here.
const SHIP_TO = ["US", "CA", "GB", "DE", "FR"];

// The value getValue() returns from the Address Element.
type Shipping = StripeAddressElementChangeEvent["value"];

export async function createPaymentIntent(shipping: Shipping): Promise<{ clientSecret: string } | { error: string }> {
  if (!SHIP_TO.includes(shipping.address.country)) return { error: "We don't ship to that country yet." };
  const intent = await stripe.paymentIntents.create({
    amount: plan.amount, // set on the server, so a buyer can't change it
    currency: plan.currency,
    automatic_payment_methods: { enabled: true }, // the card fields confirm with confirmCardPayment
    shipping: {
      name: shipping.name,
      phone: shipping.phone,
      address: { ...shipping.address, line2: shipping.address.line2 ?? undefined },
    },
  });
  return { clientSecret: intent.client_secret! };
}

app/pay/plan.ts

// What the buyer pays, in the smallest currency unit. The server action reads it; the browser only displays it.
export const plan = { name: "Pro plan", amount: 2900, currency: "usd" } as const;

app/pay/page.tsx

import Checkout from "./checkout";

// No PaymentIntent is created on page load. The server action makes one when the buyer pays.
export default function PayPage() {
  return (
    <main className="min-h-dvh bg-[#0b0a14] p-4">
      <Checkout />
    </main>
  );
}

Good to know

What the buyer sees: a Shipping address box with Stripe's fields (name, country, address, phone) and, under it, the 3D card checkout. Credit Card Checkout V1 has no address area of its own, so the Address Element sits above it in the same <Elements> group. That's a plain layout choice, not a slot of the piece.
How the address reaches Stripe. Stripe's docs say the Address Element passes the address on its own when you confirm with the Payment Element or the Express Checkout Element. Split card fields confirm with stripe.confirmCardPayment, so this file reads the address with getValue() when Pay is pressed and sends it to the server action, which puts it on the PaymentIntent as shipping.
getValue() does two jobs: it returns complete, isNewAddress and value, and it marks the incomplete fields inside the Address Element. When the address isn't complete the file throws, the card shows the message and Pay comes back.
Autocomplete: Stripe's docs say its own Google Maps key is used only when the Payment Element is in the same Elements group, or in an active Link session. With split card fields neither is true, so the file passes your own key from NEXT_PUBLIC_GOOGLE_MAPS_KEY (a key with the Places API on) and turns autocomplete off when there is none.
The billing name comes from the name typed on the card. The shipping name comes from the Address Element. They can differ, as in real life when you ship a gift.
What we ran on Oct 26 2026: every file on this page passed tsc --noEmit in strict mode and next build in a Next.js App Router app, against @stripe/stripe-js 10.1.0, @stripe/react-stripe-js 7.0.0, stripe 23.0.1, next 15.5.28, react 19.1.1, framer-motion 11.18.2 and TypeScript 5.9.3, with the shipped CardCheckout source. Three deliberate mistakes failed the check, as they should: mode "both", autocomplete mode "google_maps_api" without apiKey, and <AddressElement /> without options.
In headless Chromium at 390 and 1440 px wide, with a placeholder publishable key, Stripe.js mounted the three card field iframes inside the card. The Address Element answered that key with a load error, onLoadError caught it and the message showed under the Shipping heading, with 0 page errors and no sideways scroll. With plain inputs standing in for Stripe's iframes, the address box sits above the card and the card still flips for the CVC at both widths.
What we didn't run: we have no Stripe account on this test, so we haven't seen Stripe's real address fields or autocomplete, no PaymentIntent was created and nothing was paid. Test with your test keys before you ship.
The redirect to /thanks is not proof of payment. Fulfil orders from Stripe's payment_intent.succeeded webhook, and read the shipping address from the PaymentIntent there.
Set STRIPE_SECRET_KEY and NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, plus NEXT_PUBLIC_GOOGLE_MAPS_KEY if you want autocomplete. The card is drawn on a fixed 1000 x 660 stage, so the Fit wrapper in the file scales it down on phones.

Stripe Address Element in React on its own

This is the free route, and for many stores it's the whole job. AddressElement ships in @stripe/react-stripe-js 7.0.0. Put it in the same <Elements> provider as the Payment Element and Stripe does the rest.
Elements runs in deferred mode here: mode, amount and currency instead of a client secret, and the server action creates the PaymentIntent only when the buyer pays. elements.submit() runs Stripe's form checks first, and Stripe's docs say the Address Element shows its errors per field.
In shipping mode Stripe's docs say the address lands in the PaymentIntent's shipping field when you confirm, and also in billing_details if the buyer says it's their billing address too. That's why confirmPayment below has no shipping parameter.
Autocomplete needs no setup in this file. Stripe's docs say it uses a Stripe-provided Google Maps key when the Payment Element is mounted in the same Elements group as the Address Element.

app/free/address-checkout.tsx (free, no card)

"use client";
import { useState, type FormEvent } from "react";
import { loadStripe } from "@stripe/stripe-js";
import { Elements, AddressElement, PaymentElement, useStripe, useElements } from "@stripe/react-stripe-js";
import { createPaymentIntent } from "./actions";
import { plan } from "./plan";

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

function CheckoutForm() {
  const stripe = useStripe();
  const elements = useElements();
  const [message, setMessage] = useState<string | null>(null);
  const [busy, setBusy] = useState(false);

  const onSubmit = async (e: FormEvent) => {
    e.preventDefault();
    if (!stripe || !elements) return;
    setBusy(true);
    setMessage(null);
    // Runs Stripe's form checks first. Errors show inside the Elements, so there is nothing to print here.
    const { error: submitError } = await elements.submit();
    if (submitError) {
      setBusy(false);
      return;
    }
    const { clientSecret } = await createPaymentIntent();
    const { error } = await stripe.confirmPayment({
      elements,
      clientSecret,
      // No shipping here: the Address Element in shipping mode adds it to the PaymentIntent on confirm.
      confirmParams: { return_url: `${window.location.origin}/thanks` },
    });
    // Only reached on an immediate error. On success Stripe sends the buyer to return_url.
    setMessage(error.message ?? "The payment didn't go through.");
    setBusy(false);
  };

  return (
    <form onSubmit={onSubmit} className="grid w-full max-w-[480px] gap-4 text-[#F4F4F6]">
      <h2 className="m-0 text-[16px] font-semibold">Shipping address</h2>
      <AddressElement
        options={{
          mode: "shipping",
          allowedCountries: ["US", "CA", "GB"],
          fields: { phone: "always" },
          validation: { phone: { required: "always" } },
        }}
      />
      <h2 className="m-0 text-[16px] font-semibold">Payment</h2>
      <PaymentElement />
      <button disabled={!stripe || busy} className="h-12 rounded-xl bg-white font-semibold text-black disabled:opacity-50">
        {busy ? "Paying..." : "Pay"}
      </button>
      {message && <p role="alert" className="m-0 text-[14px] text-[#FF5C6C]">{message}</p>}
    </form>
  );
}

export default function AddressCheckout() {
  // Deferred mode: no PaymentIntent on page load, so Elements gets the amount and currency up front.
  return (
    <Elements stripe={stripePromise} options={{ mode: "payment", amount: plan.amount, currency: plan.currency, appearance: { theme: "night" } }}>
      <CheckoutForm />
    </Elements>
  );
}

app/free/actions.ts

"use server";
import Stripe from "stripe";
import { plan } from "./plan";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Called after elements.submit() passed. The amount is set here, so a buyer can't change it.
export async function createPaymentIntent(): Promise<{ clientSecret: string }> {
  const intent = await stripe.paymentIntents.create({
    amount: plan.amount, // must match the amount on <Elements>
    currency: plan.currency,
    automatic_payment_methods: { enabled: true },
  });
  return { clientSecret: intent.client_secret! };
}

Address Element options and events in @stripe/stripe-js 10.1.0

These are the names in StripeAddressElementOptions and the change event in @stripe/stripe-js 10.1.0, read from its type definitions on October 26, 2026.
mode is required: "shipping" or "billing". There is no third value, and <AddressElement /> without options fails the type check.
allowedCountries takes two letter country codes. blockPoBox refuses PO boxes. fields.phone is "always", "never" or "auto", and validation.phone.required is "always", "never" or "auto". display.name is "full", "split" (first and last name boxes) or "organization".
autocomplete is one of { mode: "automatic" }, { mode: "disabled" } or { mode: "google_maps_api", apiKey }. The type makes apiKey required for the Google Maps mode.
defaultValues prefills name, firstName, lastName, phone and address, and address.country is required inside it. contacts takes saved addresses (name, optional phone, full address) for a returning buyer to pick from.
The change event carries elementType, elementMode, empty, complete, isNewAddress and value. value has name, optional firstName, lastName and phone, and address with line1, line2 (a string or null), city, state, postal_code and country. getValue() returns the same complete, isNewAddress and value, and takes an optional format of "latin" or "localized".
Stripe's docs list address autocomplete for these countries: AU, BE, BR, CA, CH, DE, ES, FR, GB, IE, IN, IT, JP, MX, MY, NL, NO, NZ, PH, PL, RU, SE, SG, TR, US and ZA.

components/shipping-address.tsx

"use client";
import { AddressElement } from "@stripe/react-stripe-js";

// Inside <Elements>. Every option below is in StripeAddressElementOptions (@stripe/stripe-js 10.1.0).
export function ShippingAddress({ onDone }: { onDone: (ready: boolean) => void }) {
  return (
    <AddressElement
      options={{
        mode: "shipping",
        allowedCountries: ["US", "CA"],
        blockPoBox: true,
        fields: { phone: "always" },
        validation: { phone: { required: "always" } },
        display: { name: "split" }, // first and last name boxes
        defaultValues: { name: "Jane Doe", address: { country: "US", postal_code: "94110" } },
        contacts: [
          {
            name: "Jane Doe",
            phone: "+14155550100",
            address: { line1: "1 Market St", city: "San Francisco", state: "CA", postal_code: "94105", country: "US" },
          },
        ],
      }}
      onChange={(event) => {
        // event.value has name, address and phone; event.isNewAddress says whether the address is new.
        onDone(event.complete);
      }}
    />
  );
}

Shipping or billing mode, and getting the address to Stripe

Shipping mode collects a shipping address and, per Stripe's docs, offers the buyer to use it as the billing address too. Billing mode only collects a billing address.
Need both? Stripe's docs say you can put two Address Elements on the page, one per mode, or use shipping mode and let the Payment Element collect only the billing details it needs.
With the Payment Element or the Express Checkout Element, confirming the payment carries the address for you. In a multi page checkout, or with split card fields, read it with the change event or getValue() and send it yourself: on the PaymentIntent as shipping (the server action at the top of this page), or on the card as billing_details like the helper below.
line2 is a string or null in the Address Element's value. billing_details in Stripe.js takes it as is. The stripe server library (23.0.1) wants a string or nothing for shipping, so the server action turns null into undefined; without that, our type check failed with "Type 'null' is not assignable to type 'string | undefined'".

lib/pay-with-billing-address.ts

import type { Stripe, StripeElements } from "@stripe/stripe-js";
import { AddressElement, CardNumberElement } from "@stripe/react-stripe-js";

// With <AddressElement options={{ mode: "billing" }} /> next to split card fields:
// the address goes on the card's billing_details, and you pass it yourself.
export async function payWithBillingAddress(stripe: Stripe, elements: StripeElements, clientSecret: string) {
  const address = elements.getElement(AddressElement);
  const card = elements.getElement(CardNumberElement);
  if (!address || !card) throw new Error("Checkout fields missing.");
  const { complete, value } = await address.getValue();
  if (!complete) throw new Error("Add a complete billing address first.");
  return stripe.confirmCardPayment(clientSecret, {
    payment_method: {
      card,
      billing_details: {
        name: value.name,
        phone: value.phone,
        address: value.address, // line2 may be null, which billing_details accepts
      },
    },
  });
}

Styling the Address Element with the Appearance API

The Address Element is an iframe, so your Tailwind classes don't reach inside it. You style it with the appearance option on <Elements>, which also styles the Payment Element in the same group.
Pick a theme ("stripe", "night" or "flat"), set variables such as colorPrimary, colorBackground, colorText, fontFamily and borderRadius, then use rules for single parts like .Input, .Label, .Input:focus and .Input--invalid. labels takes "auto", "above" or "floating".
What you can't change: Stripe's docs say the layout of each Element stays the same. Rules only take Stripe's public class names, not descendant selectors like .Tab .TabLabel, and each class takes an allowlist of CSS properties.
The split card fields are the older Card Elements. They don't read appearance; they take the style option, which is why the file at the top sets both.

lib/stripe-appearance.ts

import type { Appearance } from "@stripe/stripe-js";

// Pass it once on <Elements options={{ ..., appearance }}>. It styles the Address Element and the Payment Element.
export const appearance: Appearance = {
  theme: "night",
  labels: "floating",
  variables: {
    colorPrimary: "#C6FF3D",
    colorBackground: "#12111F",
    colorText: "#F4F4F6",
    colorDanger: "#FF5C6C",
    fontFamily: "Inter, system-ui, sans-serif",
    borderRadius: "12px",
  },
  rules: {
    ".Input": { border: "1px solid #262A36", boxShadow: "none" },
    ".Input:focus": { border: "1px solid #C6FF3D" },
    ".Input--invalid": { border: "1px solid #FF5C6C" },
    ".Label": { color: "#8A8FA3" },
  },
};

Install

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

Props

renderCardFields: Stripe's split card fields inside the card's own field boxes
onConfirm: reads the Address Element with getValue(), then confirmCardPayment; throw to show the error
amount / currency: what the card shows (Stripe charges the PaymentIntent)
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

Why doesn't the Address Element autocomplete show?

Stripe's docs say Stripe's own Maps key is used only when the Payment Element is in the same Elements group, or in an active Link session. Anywhere else, pass autocomplete: { mode: "google_maps_api", apiKey } with your own key that has the Places API on. Autocomplete also only covers the countries Stripe lists, and with a strict CSP you need https://maps.googleapis.com in connect-src and script-src.

How do I validate the Address Element?

Confirming with confirmPayment or confirmSetup checks it and shows the errors in the fields. Anywhere else, call getValue(): it marks incomplete fields and returns complete, so you can stop before the payment. The change event's complete flag is there for enabling a button.

Can I use the Address Element without the Payment Element?

Yes. It works next to split card fields, as on this page, or on its own in a shipping step. You then read the address yourself with getValue() or the change event and send it to the PaymentIntent, and autocomplete needs your own Google Maps key.

Does it work with LinkAuthenticationElement?

Yes. Stripe's docs show the Link Authentication Element, the Address Element and the Payment Element created from one Elements group. When a returning Link customer signs in, Stripe fills their shipping address in the Address Element.

Do I need the 3D card to use the Address Element?

No. AddressElement is free in @stripe/react-stripe-js, and the first section has a complete file without the card. The card is for a checkout where you want the card form itself to move.

Is it safe for real payments?

Yes, with the slot as shown. Card numbers go straight into Stripe's iframes and never reach your code or your server. The address does pass through your server action, so check it there (the file checks the country) like any other form input.

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.