Docs on how to use RHF with server actions / useActionState

[mmahalwy]

Is your feature request related to a problem? Please describe.
Unclear how to use useActionState

Describe the solution you'd like
It'd be great to have some docs and standardization for how to use server actions / useActionState

Describe alternatives you've considered
Tried using LLMs which recommend two hooks and a weird use of useEffect

Additional context
Nope

[Rohit1415]

React Hook Form + useActionState (Server Actions)

With the introduction of React 19 and Server Actions, state management and data mutations are shifting significantly towards the server. useActionState creates a seamless bridge between form submissions and server-side responses, but it fundamentally differs from traditional client-side form libraries like React Hook Form.

React Hook Form is optimized for client-side state, validation, and real-time interaction, while useActionState handles server-side execution, loading states (isPending), and server responses.

This guide clarifies how to integrate these two powerful tools without them fighting each other.

---

🧭 Core Philosophy

When marrying React Hook Form with useActionState, the best approach is a strict separation of concerns:

• React Hook Form (Client): Input tracking (register), real-time feedback, and immediate client-side validation.
• Server Action (Server): Database mutation, server-side validation (e.g., uniqueness checks), and returning canonical error states or success messages.

---

🛠️ Recommended Integration Patterns

Here are the two primary patterns for integrating React Hook Form with useActionState, depending on your requirement for Progressive Enhancement.

Pattern 1: The Hybrid Client-First Approach (Recommended for highly interactive forms)

In this pattern, we rely on RHF's handleSubmit to block invalid submissions locally. If client validation passes, we manually construct FormData and pass it to the server action's dispatcher.

✅ Pros: Prevents unnecessary server requests by failing fast on the client.
❌ Cons: Requires JavaScript to submit the form (no progressive enhancement).

import { useForm } from "react-hook-form";
import { useActionState, useEffect, startTransition } from "react";
import { myServerAction } from "./actions";

export default function HybridForm() {
  const { register, handleSubmit, setError, formState: { errors } } = useForm();
  
  // 1. Initialize the action state
  const [state, formAction, isPending] = useActionState(myServerAction, null);

  // 2. Client submission handler
  const onSubmit = (data: any) => {
    // Manually trigger the action state dispatcher
    startTransition(() => {
      const formData = new FormData();
      Object.entries(data).forEach(([key, val]) => formData.append(key, val as string));
      formAction(formData);
    });
  };

  // 3. Sync server errors back to React Hook Form
  useEffect(() => {
    if (state?.errors) {
      Object.entries(state.errors).forEach(([field, message]) => {
        setError(field as any, { type: "server", message: message as string });
      });
    }
  }, [state, setError]);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label>Username</label>
        <input {...register("username", { required: "Name is required" })} />
        {errors.username && <p>{errors.username.message as string}</p>}
      </div>

      {state?.message && <p className="success">{state.message}</p>}

      <button type="submit" disabled={isPending}>
        {isPending ? "Submitting..." : "Submit"}
      </button>
    </form>
  );
}

Pattern 2: Progressive Enhancement (Server-Action First)

In this pattern, the <form> relies entirely on React 19's native action={formAction} prop. React Hook Form is used strictly to provide real-time validation feedback while typing, but does not intercept the final submission.

✅ Pros: Form continues to work perfectly even if JavaScript is disabled or fails to load.
❌ Cons: Server will receive requests even if the frontend considers them invalid (though native HTML required attributes can still block some).

import { useForm } from "react-hook-form";
import { useActionState, useEffect } from "react";
import { myServerAction } from "./actions";

export default function ProgressiveForm() {
  const { register, setError, formState: { errors } } = useForm({
    mode: "onChange" // Validate as the user types
  });
  
  const [state, formAction, isPending] = useActionState(myServerAction, null);

  // Sync server validation errors into RHF UI automatically
  useEffect(() => {
    if (state?.errors) {
      Object.entries(state.errors).forEach(([field, message]) => {
        setError(field as any, { type: "server", message: message as string });
      });
    }
  }, [state, setError]);

  return (
    {/* We do NOT use handleSubmit here. The action takes over natively. */}
    <form action={formAction}>
      <div>
        <label>Email</label>
        {/* RHF bound for real-time local UX, but native submission allowed */}
        <input 
          type="email" 
          {...register("email", { required: "Email is needed" })} 
        />
        {errors.email && <p>{errors.email.message as string}</p>}
      </div>

      <button type="submit" disabled={isPending}>
        {isPending ? "Submitting..." : "Save"}
      </button>
    </form>
  );
}

---

🎯 Handling Server Errors Gracefully

A common question is: "How do I map a 400 Bad Request directly to my inputs?"

When your server action returns a response, format it so it maps predictably to your fields.

// actions.ts
"use server"

export async function myServerAction(prevState: any, formData: FormData) {
  const email = formData.get("email");

  if (!email || !email.toString().includes("@")) {
    return {
      success: false,
      errors: {
        email: "Invalid email format detected on server."
      }
    };
  }

  // Perform DB mutation...
  return { success: true, message: "Profile Updated!" };
}

By standardizing this payload shape, your useEffect block inside your components can effortlessly iterate over state.errors and map them individually via setError("fieldName", { message }), ensuring the server errors render cleanly alongside locally generated React Hook Form errors.

---

Conclusion

You don't need to choose between React Hook Form and useActionState—they excel at different levels of the application stack. By allowing Hook Form to handle the fast, local UX interactions and using useActionState strictly as the mutation/server pipeline, you achieve the best of both architectures.