---
title: "Complex Forms Done Right"
author: "Maksym Kuzmitskyi (MaximusFT)"
published: "2026-07-30T20:08:37.504Z"
updated: "2026-08-24T23:05:00.306Z"
url: "https://zyvop.com/complex-forms-done-right-u2un5"
canonical: "https://ma-x.im/blog/complex-forms-done-right"
tags: ["Forms","React Hook Form","Architecture"]
---

# Complex Forms Done Right

![Cover image](<https://pub-03c883138afa4f88bc40a259a9109c50.r2.dev/posts/covers/1785442114991-rt0aeuo0eoq.webp>)

![Complex Forms Done Right](<https://ma-x.im/blog/complex-forms-done-right/cover.png>)

At Motorola Solutions I built a multi-step contract wizard where users selected products, services, additional options, and pricing tiers — dozens of fields that depended on each other. It wasn't just a form. It was a live calculator that recalculated totals, toggled conditional sections, and validated business rules at every step.

Later, at an insurance company, I worked on a policy builder that asked everything from property type and vehicle model to how many pets you own and how long you've had them. Every answer changed what came next. Every combination produced a different quote.

Forms like these are where most implementations fall apart. A simple login form? Easy. A multi-step wizard with conditional fields, async validation, dynamic pricing, and file uploads? That's a different engineering problem entirely.

## The Challenge

Complex forms have multiple concerns:

-   **State management** - Field values, touched, dirty states
    
-   **Validation** - Sync and async, field-level and form-level
    
-   **UX** - When to show errors, loading states, success feedback
    
-   **Performance** - Re-renders, large forms, dynamic fields
    
-   **Accessibility** - Screen readers, keyboard navigation, error announcements
    

## The Right Tools

After building dozens of complex forms, here's my stack:

-   **React Hook Form** - Uncontrolled forms, great performance
    
-   **Zod** - Schema validation, type inference
    
-   **TanStack Query** - Async validation, mutations
    
-   **Radix UI** - Accessible form primitives
    

## Architecture Patterns

### 1\. Schema-First Design

Define your form schema first:

```typescript
import { z } from "zod";

const addressSchema = z.object({
  street: z.string().min(1, "Street is required"),
  city: z.string().min(1, "City is required"),
  country: z.string().min(1, "Country is required"),
  postalCode: z.string().regex(/^d{5}$/, "Invalid postal code"),
});

const userSchema = z.object({
  email: z.string().email("Invalid email"),
  password: z
    .string()
    .min(8, "At least 8 characters")
    .regex(/[A-Z]/, "Need uppercase letter")
    .regex(/[0-9]/, "Need a number"),
  confirmPassword: z.string(),
  address: addressSchema,
  terms: z.literal(true, {
    errorMap: () => ({ message: "You must accept terms" }),
  }),
}).refine((data) => data.password === data.confirmPassword, {
  message: "Passwords don't match",
  path: ["confirmPassword"],
});

type UserFormData = z.infer<typeof userSchema>;
```

**One schema** defines:

-   Field types
    
-   Validation rules
    
-   Error messages
    
-   TypeScript types
    

### 2\. Async Validation

Check email availability without blocking the UI:

```typescript
const emailSchema = z.string().email().refine(
  async (email) => {
    const response = await fetch(`/api/check-email?email=${email}`);
    const { available } = await response.json();
    return available;
  },
  { message: "Email already taken" }
);
```

With React Hook Form:

```typescript
<input
  {...register("email", {
    validate: async (value) => {
      const result = await emailSchema.safeParseAsync(value);
      return result.success || result.error.errors[0].message;
    },
  })}
/>
```

### 3\. Multi-Step Forms

Break complex forms into steps:

```typescript
function MultiStepForm() {
  const [step, setStep] = useState(1);
  const methods = useForm<UserFormData>();

  const onSubmit = async (data: UserFormData) => {
    if (step < 3) {
      setStep(step + 1);
      return;
    }

    // Final submission
    await createUser(data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        {step === 1 && <PersonalInfoStep />}
        {step === 2 && <AddressStep />}
        {step === 3 && <ReviewStep />}

        <div>
          {step > 1 && (
            <button type="button" onClick={() => setStep(step - 1)}>
              Back
            </button>
          )}
          <button type="submit">
            {step < 3 ? "Next" : "Submit"}
          </button>
        </div>
      </form>
    </FormProvider>
  );
}
```

### 4\. Dynamic Field Arrays

Add/remove fields dynamically:

```typescript
import { useFieldArray } from "react-hook-form";

function SkillsForm() {
  const { control, register } = useForm();
  const { fields, append, remove } = useFieldArray({
    control,
    name: "skills",
  });

  return (
    <div>
      {fields.map((field, index) => (
        <div key={field.id}>
          <input
            {...register(`skills.${index}.name`)}
            placeholder="Skill name"
          />
          <input
            type="number"
            {...register(`skills.${index}.years`)}
            placeholder="Years"
          />
          <button type="button" onClick={() => remove(index)}>
            Remove
          </button>
        </div>
      ))}
      
      <button
        type="button"
        onClick={() => append({ name: "", years: 0 })}
      >
        Add Skill
      </button>
    </div>
  );
}
```

### 5\. Conditional Fields

Show/hide fields based on other values:

```typescript
function PaymentForm() {
  const { register, watch } = useForm();
  const paymentMethod = watch("paymentMethod");

  return (
    <div>
      <select {...register("paymentMethod")}>
        <option value="card">Credit Card</option>
        <option value="bank">Bank Transfer</option>
      </select>

      {paymentMethod === "card" && (
        <>
          <input {...register("cardNumber")} placeholder="Card Number" />
          <input {...register("cvv")} placeholder="CVV" />
        </>
      )}

      {paymentMethod === "bank" && (
        <>
          <input {...register("accountNumber")} placeholder="Account" />
          <input {...register("routingNumber")} placeholder="Routing" />
        </>
      )}
    </div>
  );
}
```

## Error Handling UX

Show errors at the right time:

```typescript
function SmartInput({ name, label, ...props }) {
  const {
    register,
    formState: { errors, touchedFields, isSubmitted },
  } = useFormContext();

  const error = errors[name];
  const showError = error && (touchedFields[name] || isSubmitted);

  return (
    <div>
      <label htmlFor={name}>{label}</label>
      <input
        id={name}
        aria-invalid={showError ? "true" : "false"}
        aria-describedby={showError ? `${name}-error` : undefined}
        {...register(name)}
        {...props}
      />
      {showError && (
        <span id={`${name}-error`} role="alert">
          {error.message}
        </span>
      )}
    </div>
  );
}
```

Only show errors after:

1.  User has touched the field, OR
    
2.  Form has been submitted
    

This prevents angry red errors while typing.

## Performance Optimization

For large forms (50+ fields):

```typescript
const { register } = useForm({
  mode: "onBlur", // Validate on blur, not on change
  shouldUnregister: true, // Unregister unmounted fields
});
```

Use `Controller` only for complex inputs:

```typescript
import { Controller } from "react-hook-form";

<Controller
  name="birthDate"
  control={control}
  render={({ field }) => (
    <DatePicker
      value={field.value}
      onChange={field.onChange}
    />
  )}
/>
```

## File Uploads

Handle files properly:

```typescript
function FileUpload() {
  const { register, watch } = useForm();
  const file = watch("avatar");

  return (
    <div>
      <input
        type="file"
        accept="image/*"
        {...register("avatar")}
      />
      {file?.[0] && (
        <img
          src={URL.createObjectURL(file[0])}
          alt="Preview"
        />
      )}
    </div>
  );
}
```

## Submission with TanStack Query

Clean mutation handling:

```typescript
function UserForm() {
  const methods = useForm<UserFormData>();
  const mutation = useMutation({
    mutationFn: createUser,
    onSuccess: () => {
      toast.success("User created!");
      methods.reset();
    },
    onError: (error) => {
      toast.error(error.message);
    },
  });

  const onSubmit = (data: UserFormData) => {
    mutation.mutate(data);
  };

  return (
    <form onSubmit={methods.handleSubmit(onSubmit)}>
      {/* fields */}
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? "Saving..." : "Save"}
      </button>
    </form>
  );
}
```

## Accessibility Checklist

✅ Labels for every input ✅ Error messages announced to screen readers ✅ Keyboard navigation works ✅ Focus management (auto-focus first error) ✅ Required fields marked ✅ Clear validation feedback

## Testing

Test forms thoroughly:

```typescript
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

test("shows validation errors", async () => {
  render(<UserForm />);
  
  const user = userEvent.setup();
  const submitButton = screen.getByRole("button", { name: /submit/i });
  
  await user.click(submitButton);
  
  await waitFor(() => {
    expect(screen.getByText(/email is required/i)).toBeInTheDocument();
  });
});
```

## Conclusion

The Motorola contract wizard and the insurance policy builder taught me the same lesson: complex forms aren't a UI problem — they're a data modeling problem. Get the schema right first, handle validation at the schema level, and the rest follows.

Schema-first validation. Smart error timing. Performance-aware rendering. Accessibility from day one. Thorough testing. Get these right, and even the most complex forms become manageable.

* * *

_Need help with complex forms?_ [_Get in touch_](<https://ma-x.im/contact>)_._