React Form Builder

Following the patterns below prevents these failures.

Core Patterns

1. Form Structure

• Use useForm from react-hook-form WITHOUT redundant generic types when using zodResolver (let the resolver infer types)
• Implement Zod schemas for validation, stored in _lib/schema/ directory
• Use @/components/ui/form components (Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage)
• Handle loading states with useTransition hook (not useState for loading)
• Implement error handling with try/catch and isRedirectError

2. Server Action Integration

• Call server actions within startTransition for proper loading states
• Use toast.promise() or toast.success()/toast.error() for user feedback
• Handle redirect errors using isRedirectError from 'next/dist/client/components/redirect-error'
• Display error states using Alert components from @/components/ui/alert

3. Code Organization

_lib/
├── schema/
│   └── feature.schema.ts    # Shared Zod schemas (client + server)
├── server/
│   └── server-actions.ts    # Server actions
└── client/
    └── forms.tsx           # Form components

4. Import Guidelines

• Toast: import { toast } from 'sonner'
• Form: import { Form, FormField, ... } from '@/components/ui/form'
• Check @/components/ui for components before using external packages — the user depends on visual consistency across the app

5. State Management

• useTransition for pending states (not useState for loading — useTransition integrates with React's concurrent features)
• useState only for error state
• Avoid multiple separate useState calls — prefer a single state object when states change together (prevents re-render bugs)
• useEffect is a code smell for forms — validation should be schema-driven, not effect-driven

6. Validation

• Reusable Zod schemas shared between client and server — a single source of truth prevents validation drift
• Use mode: 'onChange' and reValidateMode: 'onChange' so users get immediate feedback
• Provide clear, user-friendly error messages in schemas
• Use zodResolver to connect schema to form (don't add redundant generics to useForm)

7. Accessibility and UX

• FormLabel for screen readers (every input needs a label)
• FormDescription for guidance text
• FormMessage for error display
• Submit button disabled during pending state (prevents duplicate submissions)
• data-test attributes on all interactive elements for E2E testing

Error Handling Template

const onSubmit = (data: FormData) => {
  setError(false);

  startTransition(async () => {
    try {
      await serverAction(data);
    } catch (error) {
      if (!isRedirectError(error)) {
        setError(true);
      }
    }
  });
};

Toast Promise Pattern (Preferred)

const onSubmit = (data: FormData) => {
  startTransition(async () => {
    await toast.promise(serverAction(data), {
      loading: 'Creating...',
      success: 'Created successfully!',
      error: 'Failed to create.',
    });
  });
};

Complete Form Example

'use client';

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import { useTransition, useState } from 'react';
import { isRedirectError } from 'next/dist/client/components/redirect-error';
import type { z } from 'zod';

import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
import { Input } from '@/components/ui/input';
import { Button } from '@/components/ui/button';
import { Alert, AlertDescription } from '@/components/ui/alert';
import { toast } from 'sonner';

import { CreateEntitySchema } from '../_lib/schema/entity.schema';
import { createEntityAction } from '../_lib/server/server-actions';

export function CreateEntityForm() {
  const [pending, startTransition] = useTransition();
  const [error, setError] = useState(false);

  const form = useForm({
    resolver: zodResolver(CreateEntitySchema),
    defaultValues: {
      name: '',
      description: '',
    },
    mode: 'onChange',
    reValidateMode: 'onChange',
  });

  const onSubmit = (data: z.infer<typeof CreateEntitySchema>) => {
    setError(false);

    startTransition(async () => {
      try {
        await toast.promise(createEntityAction(data), {
          loading: 'Creating...',
          success: 'Created successfully!',
          error: 'Failed to create.',
        });
      } catch (e) {
        if (!isRedirectError(e)) {
          setError(true);
        }
      }
    });
  };

  return (
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <Form {...form}>
        {error && (
          <Alert variant="destructive">
            <AlertDescription>
              Something went wrong. Please try again.
            </AlertDescription>
          </Alert>
        )}

        <FormField
          name="name"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Name</FormLabel>
              <FormControl>
                <Input
                  data-test="entity-name-input"
                  placeholder="Enter name"
                  {...field}
                />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <Button
          type="submit"
          disabled={pending}
          data-test="submit-entity-button"
        >
          {pending ? 'Creating...' : 'Create'}
        </Button>
      </Form>
    </form>
  );
}

Troubleshooting

Form submits but nothing happens (no loading, no feedback)

Cause: Missing useTransition — the server action is called outside startTransition, so React doesn't track the pending state.

Fix: Wrap the server action call in startTransition(async () => { ... }) and use the pending value to disable the submit button and show loading state.

Missing 'use client' directive

Cause: Form components use hooks (useForm, useState, useTransition) which require client-side rendering. Without the directive, Next.js tries to render them on the server, causing cryptic errors.

Fix: Add 'use client'; as the very first line of any form component file.

zodResolver type mismatch with .refine()

Cause: .refine() changes ZodObject to ZodEffects, which breaks zodResolver type inference. The form types no longer match the schema types.

Fix: Create a base schema (for z.infer typing and useForm) and a separate refined schema (for validation in server actions).

Stale form data after successful submission

Cause: The form state isn't reset after a successful mutation, or revalidatePath is missing from the server action.

Fix: Call form.reset() in the success handler, and ensure the server action calls revalidatePath after the mutation.

Wrong form component imports (external packages)

Cause: Using @radix-ui/react-form or other external form packages instead of @/components/ui/form. This creates visual inconsistency and bundle bloat.

Fix: Always import form components from @/components/ui/form. Check @/components/ui first before reaching for external packages.

Components

See Components for field-level examples (Select, Checkbox, Switch, Textarea, etc.).