Stripe Embedded Checkout in Next.js: the embedded page first, then your own checkout UI

If you want Stripe's checkout on your own page with the least code, use Embedded Checkout: a Server Action creates the session, EmbeddedCheckoutProvider mounts Stripe's page in an iframe, and a return page reads the result. You can't style it with your CSS. This page shows what you can change, how to get a dark checkout, and how to switch to ui_mode elements when you want your own UI.

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

Embedded Checkout in the App Router

app/checkout/embedded-checkout.tsx

"use client";
import { loadStripe } from "@stripe/stripe-js";
import { EmbeddedCheckout, EmbeddedCheckoutProvider } from "@stripe/react-stripe-js";
import { createEmbeddedSession } from "./actions";

// Outside the component, so Stripe.js loads once and the provider gets the same Promise every render.
const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

export function EmbeddedCheckoutForm() {
  return (
    <div id="checkout" className="mx-auto w-full max-w-3xl">
      {/* The Server Action is passed as is: a stable function, called once when the provider mounts. */}
      <EmbeddedCheckoutProvider stripe={stripePromise} options={{ fetchClientSecret: createEmbeddedSession }}>
        <EmbeddedCheckout />
      </EmbeddedCheckoutProvider>
    </div>
  );
}

app/checkout/actions.ts (Server Action, creates the session)

"use server";
import { headers } from "next/headers";
import { stripe } from "@/lib/stripe";

// Called by EmbeddedCheckoutProvider when it mounts. The price comes from the server, never from the browser.
export async function createEmbeddedSession() {
  const origin = (await headers()).get("origin") ?? process.env.SITE_URL!;
  const session = await stripe.checkout.sessions.create({
    ui_mode: "embedded_page", // was "embedded" before API version 2026-03-25; the old value now fails
    mode: "payment",
    line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }],
    // Embedded Checkout uses return_url, not success_url. Stripe fills in the session id.
    return_url: `${origin}/checkout/return?session_id={CHECKOUT_SESSION_ID}`,
  });
  return session.client_secret!;
}

app/checkout/page.tsx

import { EmbeddedCheckoutForm } from "./embedded-checkout";

export default function CheckoutPage() {
  return (
    <main className="px-4 py-10">
      <EmbeddedCheckoutForm />
    </main>
  );
}

app/checkout/return/page.tsx (reads the session status)

import Link from "next/link";
import { redirect } from "next/navigation";
import { stripe } from "@/lib/stripe";

export default async function CheckoutReturn({
  searchParams,
}: {
  searchParams: Promise<{ session_id?: string }>;
}) {
  const { session_id } = await searchParams;
  if (!session_id?.startsWith("cs_")) redirect("/checkout");

  const session = await stripe.checkout.sessions.retrieve(session_id);
  if (session.status === "open") redirect("/checkout"); // they came back without paying
  if (session.status === "expired") redirect("/checkout?expired=1");

  // "unpaid" on a complete session is a delayed method (a bank debit, say) still processing.
  const paid = session.payment_status !== "unpaid";
  return (
    <main className="mx-auto max-w-md px-6 py-16">
      <h1 className="text-2xl font-semibold">
        {paid ? "Thanks, you're all set" : "Payment received, it's still processing"}
      </h1>
      {session.customer_details?.email && (
        <p className="mt-2 text-neutral-500">A receipt is on its way to {session.customer_details.email}.</p>
      )}
      <Link href="/" className="mt-8 inline-block underline">
        Back to the store
      </Link>
    </main>
  );
}

lib/stripe.ts

import Stripe from "stripe";

// Server only: never import this from a "use client" file. stripe-node 23 pins API version 2026-09-30.
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

Good to know

Since Stripe API version 2026-03-25, ui_mode takes new names: embedded_page (was embedded), elements (was custom) and hosted_page (was hosted), plus a new form value. Stripe's changelog says setting the old values now fails. stripe 23.0.1 pins API version 2026-09-30, so use the new names. TypeScript won't warn you: the type is open ended, and we checked that ui_mode: "embedded" still type-checks. The error only comes back from Stripe at run time.
fetchClientSecret gets the Server Action itself, not a new arrow function each render. The provider calls it once when it mounts. Its stripe prop can't change after the first render, so loadStripe runs once at module level.
Embedded Checkout uses return_url, not success_url. Stripe swaps {CHECKOUT_SESSION_ID} for the real id. For card payments that need no redirect, redirect_on_completion: "if_required" keeps the buyer on your page, and the provider's onComplete option lets you show your own success state there.
The return page is a convenience, not proof of payment. Record the order from the checkout.session.completed webhook as well; the success page guide linked below has a fulfil function that is safe to run from both.
lib/stripe.ts runs while next build collects page data. In our build, with STRIPE_SECRET_KEY unset, next build failed on /checkout/return with "Neither apiKey nor config.authenticator provided". Set the key in your build environment too, not only at run time.
The price comes from STRIPE_PRICE_ID on the server. A Server Action is a public endpoint, so never take the price or amount from the browser.

What you can style in Embedded Checkout, and what you can't

Stripe's appearance docs, read on October 26, 2026, say Embedded Checkout "renders inside a Stripe-owned iframe that's hosted on js.stripe.com", and that CSS from your page, including stylesheets, CSS variables and component framework styles, "has no effect on the embedded form's appearance." Tailwind classes on EmbeddedCheckout style the container, not the form.
What you can change is the Dashboard's Checkout branding, or branding_settings on each session. In stripe 23.0.1 that is background_color, button_color, border_style (rounded, pill or rectangular), font_family from Stripe's fixed list, display_name, logo and icon. Stripe's docs mark the logo and icon as full hosted page only. display_name only changes the top of the page; receipts keep your account's business name.
There is no theme or dark switch on branding_settings. The closest you get is a dark background_color picked per session, as below. We couldn't see how Stripe colours the text on it without an account, so check it in a sandbox before you ship.

app/branded/actions.ts (branding_settings per session)

"use server";
import { headers } from "next/headers";
import { stripe } from "@/lib/stripe";

// Embedded Checkout is Stripe's page in an iframe. These session fields are the styling you get.
export async function createBrandedSession(theme: "light" | "dark") {
  const origin = (await headers()).get("origin") ?? process.env.SITE_URL!;
  const session = await stripe.checkout.sessions.create({
    ui_mode: "embedded_page",
    mode: "payment",
    line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }],
    return_url: `${origin}/checkout/return?session_id={CHECKOUT_SESSION_ID}`,
    branding_settings: {
      background_color: theme === "dark" ? "#0b0b0f" : "#ffffff",
      button_color: "#8b6cff",
      border_style: "rounded", // or "pill", "rectangular"
      font_family: "inter", // one of Stripe's listed fonts, not a font file of yours
      display_name: "Northline Audio", // shown at the top only; receipts keep your account name
    },
  });
  return session.client_secret!;
}

app/branded/embedded-checkout.tsx (follows your site's theme)

"use client";
import { useCallback, useEffect, useState } from "react";
import { loadStripe } from "@stripe/stripe-js";
import { EmbeddedCheckout, EmbeddedCheckoutProvider } from "@stripe/react-stripe-js";
import { createBrandedSession } from "./actions";

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

// Reads your site's theme once, after mount. A theme switch later needs a new session, hence the key.
export function BrandedCheckout() {
  const [theme, setTheme] = useState<"light" | "dark" | null>(null);
  useEffect(() => setTheme(document.documentElement.classList.contains("dark") ? "dark" : "light"), []);
  const fetchClientSecret = useCallback(() => createBrandedSession(theme ?? "light"), [theme]);

  if (!theme) return <div className="mx-auto min-h-[600px] w-full max-w-3xl" />;
  return (
    <EmbeddedCheckoutProvider key={theme} stripe={stripePromise} options={{ fetchClientSecret }}>
      <EmbeddedCheckout className="mx-auto w-full max-w-3xl" />
    </EmbeddedCheckoutProvider>
  );
}

Dark mode: Stripe's Checkout form takes a theme

If dark mode matters, look at Stripe's Checkout form: ui_mode "form", added in the same API version. It is still Stripe's prebuilt form, and Stripe's docs say its layout stays the same, but it takes the Appearance API: the stripe, night and flat themes plus variables such as colorPrimary and colorBackground.
In @stripe/stripe-js 10.1.0 its appearance type leaves out rules, so per-selector CSS isn't available there. We checked that: passing rules fails tsc.

app/form/actions.ts

"use server";
import { stripe } from "@/lib/stripe";

export async function createFormSession() {
  const session = await stripe.checkout.sessions.create({
    ui_mode: "form", // Stripe's Checkout form: a prebuilt form you theme with the Appearance API
    mode: "payment",
    line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }],
    return_url: `${process.env.SITE_URL}/checkout/return?session_id={CHECKOUT_SESSION_ID}`,
  });
  return session.client_secret!;
}

app/form/page.tsx

import { DarkCheckoutForm } from "./checkout-form";
import { createFormSession } from "./actions";

export const dynamic = "force-dynamic";

export default async function FormPage() {
  return <DarkCheckoutForm clientSecret={await createFormSession()} />;
}

app/form/checkout-form.tsx

"use client";
import { loadStripe, type Appearance } from "@stripe/stripe-js";
import { CheckoutForm, CheckoutFormProvider } from "@stripe/react-stripe-js/checkout";

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

// "night" is Stripe's dark theme. The form takes variables but not rules (its type omits them).
const dark: Omit<Appearance, "rules"> = {
  theme: "night",
  variables: { colorPrimary: "#8b6cff", colorBackground: "#16171f", borderRadius: "12px" },
};

export function DarkCheckoutForm({ clientSecret }: { clientSecret: string }) {
  return (
    <CheckoutFormProvider stripe={stripePromise} options={{ clientSecret, appearance: dark }}>
      <CheckoutForm />
    </CheckoutFormProvider>
  );
}

Your own checkout UI: ui_mode elements inside Receipt Morph Checkout

When you want your own layout but still want Checkout Sessions (the session handles line items, tax and discounts), create the session with ui_mode "elements". Stripe's fields then render inside your page: ContactDetailsElement for the email and PaymentElement for the payment, both from @stripe/react-stripe-js/checkout. branding_settings isn't allowed here; you style the fields through elementsOptions.appearance.
Receipt Morph Checkout is our paid piece for this. Its renderCardFields slot takes the two Stripe fields, so card details never reach the component or your code. onConfirm runs checkout.confirm with redirect: "if_required", and when a card payment confirms the card splits, unrolls into a paper receipt and gets stamped PAID. The receipt reads the real line items and total from the session.
Limits, read from the piece's source and Stripe's types: the Payment Element doesn't report which field has focus or the card brand, so the card doesn't flip for the CVC and shows no brand mark. The piece formats amounts in US dollars; edit its usd formatter for another currency. onComplete's last4 stays empty, because the session the browser gets has no card details.
The PaymentIntent version of this, without Checkout Sessions, is on the shadcn checkout page guide, linked below. Receipt Morph Checkout isn't a shadcn component; you copy its files from the zip.

The PaymentIntent version in a shadcn checkout page

app/pay/actions.ts (ui_mode elements)

"use server";
import { stripe } from "@/lib/stripe";

// ui_mode "elements" (it was "custom" before 2026-03-25): your page, your layout, Stripe's fields.
export async function createElementsSession() {
  const session = await stripe.checkout.sessions.create({
    ui_mode: "elements",
    mode: "payment",
    line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }],
    // Used only when a payment method has to leave your page (a bank or wallet redirect).
    return_url: `${process.env.SITE_URL}/checkout/return?session_id={CHECKOUT_SESSION_ID}`,
  });
  return session.client_secret!;
}

app/pay/page.tsx

import { ReceiptCheckout } from "./receipt-checkout";
import { createElementsSession } from "./actions";

export const dynamic = "force-dynamic"; // a fresh Checkout Session per visit, never one baked in at build

export default async function PayPage() {
  const clientSecret = await createElementsSession();
  return (
    <main className="min-h-dvh bg-[#0b0b0f]">
      <ReceiptCheckout clientSecret={clientSecret} />
    </main>
  );
}

app/pay/receipt-checkout.tsx (Receipt Morph Checkout)

"use client";
import { useRef } from "react";
import { useRouter } from "next/navigation";
import { loadStripe, type Appearance } from "@stripe/stripe-js";
import {
  CheckoutElementsProvider,
  ContactDetailsElement,
  PaymentElement,
  useCheckoutElements,
} from "@stripe/react-stripe-js/checkout";
import { CheckoutReceiptMorph } from "@/components/CheckoutReceiptMorph";
import type { NorthwindData } from "@/data/northwind";

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

// Stripe's fields are iframes and can't read the piece's CSS, so hand them its colours.
const appearance: Appearance = {
  theme: "night",
  variables: {
    colorPrimary: "#8B6CFF",
    colorBackground: "#16171F",
    colorText: "#F4F4F6",
    colorDanger: "#FF6A3D",
    borderRadius: "12px",
  },
};

export function ReceiptCheckout({ clientSecret }: { clientSecret: string }) {
  return (
    <CheckoutElementsProvider stripe={stripePromise} options={{ clientSecret, elementsOptions: { appearance } }}>
      <ReceiptPay />
    </CheckoutElementsProvider>
  );
}

function ReceiptPay() {
  const router = useRouter();
  const state = useCheckoutElements();
  const done = useRef({ email: false, payment: false });

  if (state.type === "loading") return <div className="mx-auto h-[640px] max-w-5xl animate-pulse rounded-2xl bg-white/5" />;
  if (state.type === "error") return <p role="alert">{state.error.message}</p>;
  const { checkout } = state;

  // The receipt reads the real session. Stripe amounts are minor units; the divisor is 100 for USD.
  const unit = checkout.minorUnitsAmountDivisor;
  const order: NorthwindData["store"] = {
    name: checkout.businessName ?? "Your order",
    orderId: checkout.id.slice(-8),
    items: checkout.lineItems.map((li) => ({
      name: li.name,
      variant: li.description ?? "",
      qty: li.quantity,
      price: li.unitAmount.minorUnitsAmount / unit,
    })),
    shipping: checkout.total.shippingRate.minorUnitsAmount / unit,
    tax: checkout.total.taxExclusive.minorUnitsAmount / unit,
    total: checkout.total.total.minorUnitsAmount / unit,
  };

  return (
    <CheckoutReceiptMorph
      order={order}
      autoplayDemo={false}
      renderCardFields={(slot) => {
        // Pay unlocks once Stripe says both the email and the payment details are complete.
        const report = () => slot.onChange({ complete: done.current.email && done.current.payment });
        return (
          <div className="grid gap-3">
            <ContactDetailsElement onChange={(e) => { done.current.email = e.complete; report(); }} />
            <PaymentElement
              options={{ layout: "tabs" }}
              onChange={(e) => { done.current.payment = e.complete; report(); }}
            />
          </div>
        );
      }}
      onConfirm={async () => {
        // Cards confirm on this page, so the receipt animation is the success state.
        const result = await checkout.confirm({ redirect: "if_required" });
        return result.type === "error" ? { ok: false, message: result.error.message } : { ok: true };
      }}
      onComplete={() => setTimeout(() => router.push(`/checkout/return?session_id=${checkout.id}`), 2500)}
    />
  );
}

Embedded Checkout vs Elements vs hosted Checkout

Hosted Checkout (ui_mode hosted_page, the default): Stripe's page on Stripe's domain. Least code, full branding including logo, and a redirect away from your site and back.
Embedded Checkout (embedded_page): the same Stripe page in an iframe on your site. Little code, no redirect for cards, branding through branding_settings only.
Checkout form (form): Stripe's prebuilt form with the Appearance API, so themes and colour variables, still Stripe's layout.
Elements on Checkout Sessions (elements): Stripe's fields inside your own UI, with the session handling line items and totals. Most code, full control of everything around the fields.
Elements with a PaymentIntent and no Checkout Session: the same fields, but you compute amounts yourself. That path is on the shadcn checkout page guide.

What we checked

Read on October 26, 2026: stripe 23.0.1 (published October 22, 2026, API version 2026-09-30), @stripe/stripe-js 10.1.0 (October 13, 2026) and @stripe/react-stripe-js 7.0.0 (October 1, 2026), all MIT and the latest on npm that day. ui_mode values, branding_settings fields, redirect_on_completion, CheckoutElementsProvider, CheckoutFormProvider, useCheckoutElements, ContactDetailsElement and checkout.confirm are all in those types. The iframe quote and the logo and icon limit are from Stripe's Checkout appearance docs; the ui_mode renames are from Stripe's 2026-03-25 changelog.
Every file on this page, with Receipt Morph Checkout's shipped source, type-checks with TypeScript 5.9.3 strict and builds with next build on Next.js 15.5.28 and React 19.1.1. Four wrong calls fail tsc as they should: rules on the Checkout form appearance, redirect: "never" on confirm, appearance on EmbeddedCheckoutProvider, and reading checkout before checking the loading state.
In headless Chromium at 390 and 1440 px, the /checkout page loaded Stripe.js and Stripe's embedded checkout files; with no real keys the session request was refused, as expected. Receipt Morph ran with stand-ins for Stripe's two fields: Pay asked for the card details until they were complete, then the receipt printed, with no page errors and no sideways scroll. We don't have a Stripe account for this, so we didn't take a test payment.

Install

Copy from the zipPut react/src/components + react/src/data 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

order: the order the receipt shows (items, shipping, tax, total); built from the session above
renderCardFields: slot for Stripe's ContactDetailsElement and PaymentElement; card details never reach the component
onConfirm: run checkout.confirm, return ok or a message
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

Can I style Stripe Embedded Checkout with CSS or Tailwind?

No. It runs in an iframe on js.stripe.com, and Stripe's docs say your CSS doesn't cross into it. Use Dashboard branding or branding_settings on the session: background colour, button colour, border style, font and display name.

Does Stripe Embedded Checkout have a dark mode?

Not as a theme. You can pass a dark background_color per session. If you want Stripe's night theme, use the Checkout form (ui_mode "form") with appearance: { theme: "night" }.

Why does ui_mode "embedded" fail?

Stripe renamed it to embedded_page in API version 2026-03-25 and the old value now fails. TypeScript doesn't catch it, so check your session code when you upgrade stripe.

Can I put my own components inside Embedded Checkout?

No. For your own UI around Stripe's fields, use ui_mode "elements" with CheckoutElementsProvider, as in the Receipt Morph Checkout section.

Does Receipt Morph Checkout work with Embedded Checkout?

No. Embedded Checkout is Stripe's whole page in an iframe. Receipt Morph Checkout goes with ui_mode "elements" or with a PaymentIntent, where Stripe's fields sit in its slot.

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.