Build Dynamic Payment Forms in React and Next.js

Building dynamic payment forms in React and Next.js requires choosing between hook-based libraries, schema-driven tools, and headless form backends. Each approach balances developer control, performance, and the ability to handle conditional fields like showing BIC only for bank transfers or validating card versus crypto payments differently.

Recent shifts in 2026 include the maturation of Zod for runtime schema composition and the requirement that Next.js developers place all form logic in client components due to Server Component restrictions. React Hook Form's useFieldArray and watch() functions now provide standard patterns for adding line items and implementing real-time conditional rendering without full re-renders.

Dynamic Payment Form Capabilities

A dynamic payment form adapts its fields, validation rules, and payment method options based on user input or context without requiring a page reload. This means the form can show a credit card number field only when the user selects "card," or request a bank routing number when they choose ACH, all within the same component. The core mechanism relies on a state-driven rendering pattern where a parent component tracks the selected payment method and conditionally renders the corresponding field group. React Hook Form handles this efficiently because it uses uncontrolled field registration with refs, minimizing re-renders even when the form's structure changes frequently. For a checkout flow, this eliminates the friction of multi-step pages or hidden fields that confuse users.

Stripe's Payment Element is a production-ready example of this pattern. It accepts payment methods from around the globe with a secure, embeddable UI component that handles conditional logic for different payment methods internally. When you integrate the Payment Element, Stripe decides which fields to show based on the currency, country, and enabled payment methods you configure on your dashboard. This saves you from writing conditional rendering logic for dozens of payment types. For custom implementations, you can build the same behavior using a JSON schema that defines field groups per method, then map that schema to React components using a switch statement or a lookup table. SurveyJS treats a form as a JSON schema rather than a component tree, enabling dynamic field generation from a configuration object without manual JSX, which works well for complex admin panels but adds overhead for simple checkout flows.

For checkout flows and simple settings screens, React Hook Form plus Zod is simpler and faster to build than schema-driven tools like SurveyJS. Zod provides type-safe parsing and boundary validation for dynamic form schemas, catching type errors at build time in TypeScript projects. This means if your schema defines a field as a string with a minimum length of 3, Zod will enforce that rule at runtime and give you a typed error object you can map directly to form field messages. React Query (TanStack Query) handles form submission, retries, caching, and server sync for dynamic payment forms, reducing boilerplate for API interactions. When a user switches from card to PayPal, you can invalidate the cached payment intent and fetch a new one without reloading the page.

A common mistake is placing dynamic form logic inside a Next.js Server Component. Server Components cannot use hooks like useState or useEffect, nor can they access browser APIs. Any dynamic form logic must live in a client component with the 'use client' directive. This includes state for the selected payment method, conditional field rendering, and form submission handlers. You can still fetch initial data like available payment methods in a parent Server Component and pass it as props to the client form component.

To test this pattern today, open a new Next.js project and create a client component that renders a radio button group for payment methods. Use React Hook Form's useForm to register the radio group and a conditional text input for the card number. Add a Zod schema that validates the card number only when the selected method equals "card." This gives you a working dynamic form in under fifty lines of code, and you can extend it with additional methods and validation rules as your checkout requirements grow.

JSON Schema-Driven Field Rendering

A JSON schema drives dynamic field rendering by acting as a single source of truth for form structure, validation rules, and conditional logic. Instead of hardcoding JSX for each payment method, you define a configuration object that describes every field, its type, its dependencies, and its validation constraints. A renderer component then iterates over that schema and produces the appropriate React elements at runtime. This approach decouples form logic from presentation, allowing you to change the form layout or add new payment methods by editing the schema alone, without touching component code.

The mechanism works through a three-layer architecture. The data schema defines the shape of the submitted data, including field names, types, and required status. The UI schema specifies layout details like field order, grouping, and labels. A third layer, the conditional schema, defines rules for showing or hiding fields based on the value of another field. For a payment form, this means the schema for a credit card number only renders when the selected payment method equals "card," while a crypto wallet address field appears only when the method equals "wallet." Libraries like SurveyJS treat the entire form as a JSON schema rather than a component tree, enabling dynamic field generation from a configuration object without manual JSX. For checkout flows and simple settings screens, React Hook Form plus Zod is simpler and faster to build than schema-driven tools like SurveyJS, but SurveyJS excels when you need to generate forms from a backend API response or allow non-developers to configure form layouts.

React Hook Form uses uncontrolled field registration with refs, making it suitable for dynamic forms with many fields. When combined with a JSON schema, you register fields conditionally based on the schema's rules. For example, you can map over the schema array and call register for each field that passes the conditional check, then render the corresponding input component. Zod provides type-safe parsing and boundary validation for dynamic form schemas, catching type errors at build time in TypeScript projects. You can generate a Zod schema dynamically from your JSON configuration, ensuring that validation rules stay in sync with the form structure. React Query (TanStack Query) handles form submission, retries, caching, and server sync for dynamic payment forms, reducing boilerplate for API interactions. When a user switches from card to PayPal, you can invalidate the cached payment intent and fetch a new one without reloading the page.

A common edge case occurs when the schema includes deeply nested conditional logic, such as showing a bank transfer reference field only when the user selects a specific bank from a dropdown. The renderer must evaluate dependencies recursively, checking parent field values before rendering child fields. React Hook Form's watch function handles this efficiently by subscribing to specific field values without triggering full re-renders. Another edge case is schema versioning: if your backend updates the schema between page loads, the client must handle fields that no longer exist or new fields that require data. You can manage this by fetching the schema on mount and storing it in React state, then using a useEffect to re-fetch when the payment method changes. A caveat: pure JSON Schema does not encode layout. You need a separate UI schema to specify which fields go in which section, what order they appear in, and what hints to display. Without this separation, you end up embedding layout logic in the data schema, which defeats the purpose of dynamic rendering.

State Management for Conditional Fields

For conditional fields in a dynamic payment form, React Hook Form combined with local component state works best for most checkout flows. This approach minimizes re-renders by using uncontrolled field registration with refs, which is critical when a form contains many conditional fields that appear or disappear based on payment method selection. When a user switches from card to PayPal, only the fields for the newly selected method mount, and React Hook Form registers them without re-rendering the entire form tree.

The mechanism works by storing the selected payment method in a local useState hook, then using that value to determine which fields from the JSON schema to render. React Hook Form's useForm hook registers fields dynamically by iterating over the schema array and calling register for each field that passes the conditional check. This pattern avoids the overhead of a global state library like Redux or Zustand for form state, because the conditional logic is scoped to a single checkout component and does not need to be shared across unrelated parts of the application.

Another edge case is schema versioning. If your backend updates the schema between page loads, the client must handle fields that no longer exist or new fields that require data. You can manage this by fetching the schema on mount and storing it in React state, then using a useEffect to re-fetch when the payment method changes. React Query (TanStack Query) handles this caching and invalidation automatically, reducing boilerplate for API interactions. When a user switches from card to PayPal, you can invalidate the cached payment intent and fetch a new one without reloading the page.

A caveat: pure JSON Schema does not encode layout. You need a separate UI schema to specify which fields go in which section, what order they appear in, and what hints to display. Without this separation, you end up embedding layout logic in the data schema, which defeats the purpose of dynamic rendering. For checkout flows and simple settings screens, React Hook Form plus Zod is simpler and faster to build than schema-driven tools like SurveyJS, but SurveyJS excels when you need to generate forms from a backend API response or allow non-developers to configure form layouts.

How to Validate Dynamic Fields in Real Time with Zod

Zod schemas can be composed dynamically at runtime to validate form fields that change based on user input, such as different validation rules for card versus crypto payments. The core mechanism is a factory function that accepts a payment method identifier and returns a Zod object with the appropriate fields and constraints. For a card payment, the schema requires a 16-digit card number, a three-digit CVC, and an expiry date in MM/YY format. For a crypto payment, the schema requires a wallet address string and a network selection from a fixed set of values. You call this factory function inside a React Hook Form component whenever the user changes the payment method selector, then pass the new schema to the zodResolver from @hookform/resolvers.

An edge case arises with conditional fields that depend on a sub-selection within the same payment method. A bank transfer schema might have a dropdown for the bank name, and only when the user selects a specific bank does a reference number field appear. You handle this by composing a base schema for the bank transfer and then using z.discriminatedUnion with the bank selection as the discriminator. The discriminated union evaluates the bank field value and applies the corresponding sub-schema, which includes the reference field only for the matching bank. This pattern keeps the validation logic declarative and avoids manual if-else chains in the component.

Zod provides type-safe parsing and boundary validation for dynamic form schemas, catching type errors at build time in TypeScript projects. When you define the factory function with a return type of z.ZodObject, TypeScript infers the shape of the validated data. This means you can use z.infer to derive a TypeScript type from the dynamic schema and use it as the generic parameter for useForm. The compiler then flags any mismatch between the form data type and the fields you register, reducing runtime errors.

A common mistake is to define a single monolithic Zod schema that tries to cover all payment methods with optional fields. This approach leads to validation gaps because optional fields pass validation even when they should be required for a specific method. The factory pattern avoids this by generating a precise schema for each method, ensuring that required fields are enforced and irrelevant fields are excluded. For checkout flows and simple settings screens, React Hook Form plus Zod is simpler and faster to build than schema-driven tools like SurveyJS, but SurveyJS excels when you need to generate forms from a backend API response or allow non-developers to configure form layouts.

Step-by-Step: Building a Multi-Method Payment Form with React Hook Form

Start by installing React Hook Form and Zod in your Next.js project. Run npm install react-hook-form @hookform/resolvers zod. This gives you the two core libraries: React Hook Form for form state management and Zod for schema-based validation. React Hook Form minimizes re-renders by using uncontrolled field registration with refs, which matters when your payment form has many conditional fields. Controlled forms built with useState re-render on every keystroke, causing input lag with 20 or more dynamic fields. Uncontrolled registration avoids that entirely.

Create a client component with the 'use client' directive. Define a Zod factory function that accepts a payment method string and returns the appropriate schema. For a credit card method, the schema requires cardNumber, expiry, and cvc. For a bank transfer method, the schema requires accountNumber and sortCode. For a crypto wallet method, the schema requires walletAddress and network. The factory pattern generates a precise schema for each method, ensuring required fields are enforced and irrelevant fields are excluded. This avoids the common mistake of a single monolithic schema with optional fields that pass validation when they should be required.

Set up useForm with zodResolver and pass the factory function's output as the validation schema. Use watch('paymentMethod') to observe the selected method. Inside a useEffect that depends on the payment method value, call reset with the default values for the new schema. This clears stale field values from the previous method. For example, if a user enters a card number and then switches to crypto, the card number field disappears but its value remains in the form data. Calling reset({ paymentMethod: 'crypto' }) clears those stale values and sets the defaults for the new schema.

Render a radio button group for the payment method selection. Conditionally render the fields defined in the schema for the selected method. Use React Hook Form's watch() function to enable real-time conditional logic within a single method. For bank transfer, you might have a dropdown for the bank name. When the user selects a specific bank, a reference number field appears. Compose a base schema for bank transfer and use z.discriminatedUnion with the bank selection as the discriminator. The discriminated union evaluates the bank field value and applies the corresponding sub-schema, which includes the reference field only for the matching bank. This keeps validation logic declarative and avoids manual if-else chains.

For merchant checkout forms that need dynamic line items, use React Hook Form's useFieldArray hook. This hook allows users to dynamically add or remove line items, managing array state and field registration. Each line item can have its own quantity, price, and product ID fields. The hook handles the array indexing and registration automatically, so you can focus on rendering the add and remove buttons. This pattern works well for invoice-style payment forms where the number of items is not known in advance.

An edge case arises when you need to derive a TypeScript type from the dynamic schema. When you define the factory function with a return type of z.ZodObject, TypeScript infers the shape of the validated data. Use z.infer to derive a TypeScript type from the dynamic schema and pass it as the generic parameter for useForm. The compiler then flags any mismatch between the form data type and the fields you register, reducing runtime errors. For checkout flows and simple settings screens, React Hook Form plus Zod is simpler and faster to build than schema-driven tools like SurveyJS. SurveyJS excels when you need to generate forms from a backend API response or allow non-developers to configure form layouts.

How to Integrate Dynamic Forms with Stripe and Coinbase Commerce

Integrate a dynamic payment form with Stripe and Coinbase Commerce by separating the payment method selection from the payment processing logic. The form collects the payment details and amount, then passes the selected method and data to the respective SDK for tokenization or charge creation. Coinbase Commerce accepts crypto payments (Bitcoin, Ethereum, USDC) and returns a checkout URL or charge ID without storing sensitive wallet data on your server.

For Stripe, render the Payment Element inside a client component using the 'use client' directive. Import loadStripe from @stripe/stripe-js and Elements from @stripe/react-stripe-js. Create a PaymentIntent on your server route (POST /api/create-payment-intent) that returns a clientSecret. Pass that secret to the Elements provider. The Payment Element itself detects the customer's browser and location to show relevant methods — cards, wallets, bank transfers, buy-now-pay-later — without you writing conditional JSX. When the user submits the form, call stripe.confirmPayment() with the clientSecret. This approach keeps PCI-sensitive data off your server because Stripe handles tokenization inside the iframe.

Coinbase Commerce works differently. It does not provide an embeddable iframe for card entry. Instead, your form collects the amount and optional metadata (order ID, customer email), then calls the Coinbase Commerce API to create a charge. The API returns a hosted checkout URL. Redirect the user to that URL, or display it as a QR code for in-person payments. The charge object includes a timeline status (NEW, PENDING, COMPLETED, EXPIRED) that you poll via webhook or the List Charges endpoint. Coinbase Commerce supports 10+ cryptocurrencies and settles to USDC by default, which avoids crypto price volatility for merchants.

A practical integration pattern uses a single form component that switches between Stripe and Coinbase based on a radio button. When the user selects "Credit Card," render the Stripe Payment Element. When they select "Crypto," hide the Payment Element and show a "Pay with Crypto" button that triggers the Coinbase charge creation. Use React Hook Form's watch('paymentMethod') to toggle the visible section. The form state for the amount and customer details remains shared across both methods, so you only need one set of validation rules for those fields. Use Zod to validate the amount (must be a positive number) and email (valid email format) before calling either API.

An edge case occurs when the user switches from Stripe to Coinbase after the Payment Element has mounted. The Payment Element maintains its own internal state, so switching methods does not cause a validation error. However, you must destroy the Elements provider when the method changes to avoid memory leaks. Conditionally render the Elements provider only when the selected method is "card." Use a useEffect cleanup function to tear down the Stripe instance when the component unmounts or the method changes. For Coinbase, no cleanup is needed because the charge creation is a simple fetch call.

React Query (TanStack Query) reduces boilerplate for both integrations. Use useMutation for the Stripe PaymentIntent creation and for the Coinbase charge creation. The mutation handles loading states, error handling, and retries. For Stripe, the mutation returns the clientSecret, which you pass to the Elements provider. For Coinbase, the mutation returns the hosted checkout URL, which you open with window.open or route the user to. React Query also caches the clientSecret so you do not re-create a PaymentIntent on every re-render.

What Are the Common Pitfalls When Mixing Server and Client Components?

Mixing server and client components in a Next.js payment form creates a specific set of architectural constraints that many developers discover only after a failed build. The core rule is simple: any component that uses React hooks (useState, useEffect, useRef), browser APIs (localStorage, window, document), or event handlers (onClick, onChange) must carry the 'use client' directive. Server components cannot use any of these. A dynamic payment form that reads the payment method from a radio button, toggles between Stripe and Coinbase, and validates fields with Zod must be a client component at the point where that logic lives. The common mistake is placing the form logic in a parent server component and trying to pass interactive state down through props that the server cannot manage.

The most frequent pitfall involves data fetching patterns. Server components can fetch data directly with async/await, but client components cannot. If your payment form needs to load a list of supported currencies or a merchant configuration from a database, you must fetch that data in a parent server component and pass it as props to the client form component. Do not attempt to fetch inside the client component with useEffect for data that could be fetched on the server. This causes unnecessary network waterfalls and slower initial page loads. A better pattern is to create a server component wrapper that fetches the configuration, then renders the client form component with that data as props. The form component receives the configuration as a plain object and uses it to render dynamic fields.

Another common issue is pre-populating form fields from URL query strings. Next.js provides useSearchParams() for client components and the searchParams prop for server components. If you need to read a query parameter like ?amount=49.99 to pre-fill the payment amount, do it in the server component and pass the value as a default prop to the client form. Using useSearchParams() inside the client component works, but it triggers a client-side re-render after hydration, which can cause a flash of empty fields. The server-side approach avoids that flicker entirely. For dynamic forms that change field structure based on query parameters, pass the entire parsed schema from the server to the client as a JSON object.

Memory leaks from conditional rendering of Stripe Elements are a third pitfall specific to payment forms. As noted above, the Stripe Payment Element maintains its own internal state. When a user switches from credit card to crypto and back, the Elements provider must be destroyed and recreated. If the provider lives in a client component that is conditionally rendered based on a state variable, React handles the unmount and mount cycle correctly. The mistake is placing the Elements provider in a parent server component that wraps the entire form. The server component cannot conditionally render the provider based on client-side state. The fix is to keep the Elements provider inside the client component, wrapped in a conditional that checks the selected payment method. Use a useEffect cleanup function to call elements.destroy() when the method changes, preventing stale event listeners.

React Hook Form minimizes re-renders by using uncontrolled field registration with refs, which makes it suitable for dynamic forms with many fields. However, when the form schema changes dynamically (for example, adding a crypto wallet address field only when crypto is selected), you must call register and unregister for the new fields. Failing to unregister removed fields leaves stale data in the form state, which can cause validation errors or submission of phantom fields. Use the watch method to detect schema changes and call unregister in a useEffect for fields that no longer exist. Zod validation schemas should be generated dynamically from the same configuration object that drives the field rendering, ensuring that the validation rules match the visible fields exactly.

For a concrete action today, audit your current payment form component tree. Identify every component that uses hooks or browser APIs and ensure it has the 'use client' directive. Move all data fetching to server component parents. Verify that your Stripe Elements provider is inside the client boundary and that you call unregister for dynamic fields when the payment method changes. Test the form by switching methods rapidly in a browser and checking the console for memory leak warnings or stale state errors.

What to do next

Building dynamic payment forms in React and Next.js requires choosing the right combination of libraries and understanding where client-side logic lives. The following steps will help you evaluate your options and implement a production-ready solution based on your specific use case.

Also worth reading: Adaptive Streaming for Crypto Platforms Dashjs React Deep Dive · Exploring the 90 Day Build for Crypto Design Systems · How Fungi Build Resilience Lessons for Crypto Ecosystems · Simple Ways Millionaires Use Passive Income To Build Wealth

Sources: smashingmagazine, nextbuild, nextjs, debugged-pro, pkgpulse