React Hook Form 20 📋 Server Actions Integration — React 19 and Next.js patterns
The Server Actions are the React 19 and Next.js mechanism for the mutations that run on the server, and the React Hook Form is the client-side state manager. The two are not the same layer, and the integration is the question of where the validation and the form state live. The Next.js documentation offers two patterns: the client-side validation with the React Hook Form (the zodResolver or the yupResolver) plus the Server Action for the mutation, and the server-side validation with the useActionState hook and the Server Action as the form action. The React Hook Form pattern is the choice when the form needs the rich client-side features—the dynamic fields, the watch, the formState subscription—and the Server Action pattern is the choice when the form is the simple and the server is the source of truth.
The integration pattern that the Next.js documentation recommends for the React Hook Form is the Client Component that calls the Server Action. The handleSubmit validates the form on the client, and the onSubmit handler calls the Server Action with the typed data. The useTransition is the mechanism that tracks the Server Action’s pending state, and the formState.isSubmitting is the React Hook Form’s own state . The Server Action is the separate function with the 'use server' directive, and the directive is the marker that makes the function callable from the client. The two validations—the client and the server—are the defense in depth, and the depth is the reason the Server Action re-validates the input even when the client already did.
Key point: The React Hook Form and the Server Actions are the two separate layers. The useForm with the resolver validates on the client, and the onSubmit handler calls the Server Action with the validated data. The useTransition is the pending-state mechanism for the Server Action, and the formState.isSubmitting is the React Hook Form’s state. The Server Action re-validates the input because the client validation is the untrusted convenience, and the server validation is the security boundary.
Why the integration needs the two validations
The client-validation problem. The React Hook Form validates the form on the client, and the client validation is the UX mechanism—the immediate error, the focus on the field, the disabled submit button. The client validation is not the security mechanism, because the client code can be bypassed, and the Server Action is the public endpoint that any client can call with any payload . The server validation is the mechanism that keeps the invalid data out of the database, and the Server Action is the place where the server validation runs.
The pending-state problem. The Server Action is the async function, and the form needs to show the pending state while the action runs. The useTransition is the mechanism that tracks the action’s pending state, and the isPending is the boolean that the UI reads . The React Hook Form’s formState.isSubmitting is the separate state that tracks the handleSubmit‘s async handler, and the two are the different mechanisms that the integration must coordinate.
The error problem. The Server Action can fail with the validation error, the authorization error, or the unexpected exception. The setError is the mechanism that maps the server error to the React Hook Form’s field, and the mapping is the reason the server error appears in the same place as the client error . The action’s return value is the mechanism that carries the error, and the return value is the reason the client can display it.
The re-validation problem. The Next.js documentation states the rule plainly: “Always re-validate the input on the server, even if the client validation passes” . The re-validation is the mechanism that keeps the malicious client from bypassing the client checks, and the bypass is the reason the Server Action does not trust the payload.
The progressive-enhancement problem. The React Hook Form is the Client Component, and the Client Component requires the JavaScript. The Server Action as the form action is the mechanism that works without the JavaScript, and the useActionState is the pattern that the Next.js documentation recommends for the progressive enhancement . The React Hook Form pattern and the useActionState pattern are the two ends of the spectrum, and the choice is the client features against the progressive enhancement.
a. The React Hook Form and the Server Action
The Client Component calls the useForm with the resolver, and the handleSubmit calls the Server Action. The useTransition is the mechanism that tracks the pending state.
// The Server Action
'use server';
import { z } from 'zod';
import { db } from '@/lib/db';
// The server-side schema is the separate source of truth.
const schema = z.object({
name: z.string().min(2),
email: z.string().email(),
});
export async function createUser(formData: FormData) {
// The Server Action re-validates the input.
const parsed = schema.safeParse({
name: formData.get('name'),
email: formData.get('email'),
});
if (!parsed.success) {
// The return value carries the error to the client.
return { error: 'Invalid input' };
}
await db.user.create({ data: parsed.data });
return { error: null };
}// The Client Component
'use client';
import { useForm } from 'react-hook-form';
import { useTransition } from 'react';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { createUser } from '@/app/actions';
// The client schema mirrors the server schema.
const schema = z.object({
name: z.string().min(2, 'At least 2 characters'),
email: z.string().email('Invalid email'),
});
type FormValues = z.infer<typeof schema>;
function UserForm() {
const [isPending, startTransition] = useTransition();
const {
register,
handleSubmit,
formState: { errors },
} = useForm<FormValues>({
resolver: zodResolver(schema),
});
const onSubmit = (data: FormValues) => {
// The startTransition tracks the Server Action's pending state.
startTransition(async () => {
const formData = new FormData();
formData.append('name', data.name);
formData.append('email', data.email);
// The Server Action is called with the FormData.
const result = await createUser(formData);
if (result.error) {
// The server error is mapped to the form.
setError('root.server', { message: result.error });
}
});
};
return (
<form onSubmit={handleSubmit(onSubmit)}>
<input {...register('name')} disabled={isPending} />
{errors.name && <p role="alert">{errors.name.message}</p>}
<input {...register('email')} disabled={isPending} />
{errors.email && <p role="alert">{errors.email.message}</p>}
{errors.root?.server && <p role="alert">{errors.root.server.message}</p>}
<button type="submit" disabled={isPending}>
{isPending ? 'Saving…' : 'Save'}
</button>
</form>
);
}The startTransition(async () => { ... }) is the mechanism that tracks the Server Action’s pending state. The isPending is the boolean that the UI reads, and the UI is the reason the user sees the disabled state . The createUser(formData) is the Server Action call, and the formData is the mechanism that carries the values.
The errors.root.server is the mechanism that displays the server-level error. The setError('root.server', { message }) is the mechanism that maps the action’s return value to the form’s root error, and the root error is the reason the general failure is visible .
The two validations are the defense in depth. The client zodResolver(schema) is the immediate feedback, and the server schema.safeParse is the security boundary . The two schemas are the same shape, and the shape is the reason the messages match.
b. The useActionState pattern and the progressive enhancement
The useActionState is the React 19 hook that the Next.js documentation recommends for the Server Action forms. The hook manages the state and the pending flag, and the form works without the JavaScript.
// The Server Action with the useActionState
'use server';
import { z } from 'zod';
import { db } from '@/lib/db';
const schema = z.object({
name: z.string().min(2),
email: z.string().email(),
});
export async function createUser(prevState, formData) {
const parsed = schema.safeParse({
name: formData.get('name'),
email: formData.get('email'),
});
if (!parsed.success) {
// The return value becomes the state.
return { error: 'Invalid input' };
}
await db.user.create({ data: parsed.data });
return { error: null };
}// The Client Component with the useActionState
'use client';
import { useActionState } from 'react';
import { createUser } from '@/app/actions';
function UserForm() {
// The hook returns the state, the wrapped action, and the pending flag.
const [state, formAction, pending] = useActionState(createUser, { error: null });
return (
<form action={formAction}>
<input name="name" disabled={pending} />
<input name="email" disabled={pending} />
{state.error && <p role="alert">{state.error}</p>}
<button type="submit" disabled={pending}>
{pending ? 'Saving…' : 'Save'}
</button>
</form>
);
}The useActionState(createUser, { error: null }) is the mechanism that manages the state and the pending flag. The formAction is the wrapped action that the form’s action prop receives, and the action prop is the mechanism that works without the JavaScript . The state.error is the mechanism that displays the server error, and the pending is the mechanism that disables the inputs.
The two patterns are the different ends of the spectrum. The React Hook Form pattern is the client-heavy with the rich features, and the useActionState pattern is the server-heavy with the progressive enhancement. The Next.js documentation states the choice: the useActionState is the “recommended pattern for Server Actions”, and the React Hook Form is the choice “when you need client-side features like dynamic fields, complex validation, or the formState subscription” .
Complete Example Session
// ============================================
// PART 1: THE SERVER ACTION
// ============================================
'use server';
import { z } from 'zod';
const schema = z.object({
name: z.string().min(2),
email: z.string().email(),
});
export async function createUser(formData: FormData) {
const parsed = schema.safeParse({
name: formData.get('name'),
email: formData.get('email'),
});
if (!parsed.success) {
return { error: 'Invalid input' };
}
await db.user.create({ data: parsed.data });
return { error: null };
}
// ============================================
// PART 2: THE CLIENT FORM WITH THE REACT HOOK FORM
// ============================================
'use client';
import { useForm } from 'react-hook-form';
import { useTransition } from 'react';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import { createUser } from '@/app/actions';
const schema = z.object({
name: z.string().min(2, 'At least 2 characters'),
email: z.string().email('Invalid email'),
});
type FormValues = z.infer<typeof schema>;
function UserForm() {
const [isPending, startTransition] = useTransition();
const { register, handleSubmit, setError, formState: { errors } } = useForm<FormValues>({
resolver: zodResolver(schema),
});
const onSubmit = (data: FormValues) => {
startTransition(async () => {
const formData = new FormData();
formData.append('name', data.name);
formData.append('email', data.email);
const result = await createUser(formData);
if (result.error) {
setError('root.server', { message: result.error });
}
});
};
return (
<form onSubmit={handleSubmit(onSubmit)}>
<input {...register('name')} disabled={isPending} />
{errors.name && <p>{errors.name.message}</p>}
<input {...register('email')} disabled={isPending} />
{errors.email && <p>{errors.email.message}</p>}
{errors.root?.server && <p>{errors.root.server.message}</p>}
<button disabled={isPending}>{isPending ? 'Saving…' : 'Save'}</button>
</form>
);
}
// ============================================
// PART 3: THE USE ACTION STATE PATTERN
// ============================================
'use client';
import { useActionState } from 'react';
import { createUser } from '@/app/actions';
function UserForm() {
const [state, formAction, pending] = useActionState(createUser, { error: null });
return (
<form action={formAction}>
<input name="name" disabled={pending} />
<input name="email" disabled={pending} />
{state.error && <p>{state.error}</p>}
<button disabled={pending}>{pending ? 'Saving…' : 'Save'}</button>
</form>
);
}
// ============================================
// PART 4: THE TWO VALIDATIONS
// ============================================
// The client validation: the zodResolver(schema).
// The server validation: the schema.safeParse in the action.
// The two are the same shape.
// ============================================
// PART 5: THE PENDING STATE
// ============================================
// The useTransition's isPending.
// The useActionState's pending.
// ============================================
// PART 6: THE SERVER ERROR
// ============================================
// The setError("root.server", { message }).
// The state.error in the useActionState.
// ============================================
// PART 7: THE REVALIDATION
// ============================================
// The Server Action re-validates the input.
// The client validation is the convenience.
// ============================================
// PART 8: THE PROGRESSIVE ENHANCEMENT
// ============================================
// The React Hook Form requires the JavaScript.
// The useActionState works without the JavaScript.
// ============================================
// PART 9: THE CHOICE
// ============================================
// The React Hook Form: the dynamic fields, the watch, the formState.
// The useActionState: the simple form, the progressive enhancement.
// ============================================
// PART 10: THE CHECKLIST
// ============================================
// [ ] The Server Action has the 'use server' directive.
// [ ] The Server Action re-validates the input.
// [ ] The client validation is the zodResolver.
// [ ] The useTransition tracks the Server Action.
// [ ] The setError maps the server error.
// [ ] The useActionState is the progressive-enhancement alternative.The ten parts covered the Server Action, the client form with the React Hook Form, the useActionState pattern, the two validations, the pending state, the server error, the revalidation, the progressive enhancement, the choice, and the checklist. The through-line is that the Server Action is the security boundary, and the React Hook Form is the client convenience.
Quick Reference
The two patterns
| Aspect | React Hook Form | useActionState |
|---|---|---|
| The validation | The client resolver + the server | The server only |
| The pending | The useTransition‘s isPending | The hook’s pending |
| The error | The setError | The state.error |
| The progressive enhancement | No | Yes |
| The client features | The full set | The limited |
The Server Action
| Aspect | Detail |
|---|---|
| The directive | The 'use server' |
| The input | The FormData |
| The validation | The schema.safeParse |
| The return | The { error } |
| The revalidation | The required |
The pending state
| Mechanism | Source |
|---|---|
The useTransition | The React Hook Form pattern |
The useActionState | The progressive-enhancement pattern |
The formState.isSubmitting | The React Hook Form’s own |
The error display
| Source | Path |
|---|---|
| The client validation | The errors.field |
| The server validation | The errors.root.server |
The useActionState | The state.error |
Best Practices
✅ Do This:
// Re-validate on the server
const parsed = schema.safeParse(data); // ✅
// Use the useTransition for the pending state
startTransition(async () => { await createUser(formData); }); // ✅
// Map the server error to the form
setError('root.server', { message: result.error }); // ✅
// Use the useActionState for the progressive enhancement
const [state, formAction, pending] = useActionState(createUser, {}); // ✅❌ Don’t Do This:
// Trust the client validation alone
await db.user.create({ data }); // the bypass risk // ❌
// Call the Server Action without the transition
await createUser(formData); // the pending state is not tracked // ❌
// Assume the React Hook Form works without the JavaScript
// The progressive enhancement requires the useActionState. // ❌Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| The Server Action is not revalidating | The client validation is trusted | Add the schema.safeParse |
| The pending state is not shown | The useTransition is missing | Use the useTransition |
| The server error is not displayed | The setError is missing | Map the root.server |
| The form does not work without the JS | The React Hook Form is used | Use the useActionState |
Real-World Examples
1. The Server Action
'use server'; export async function createUser(formData: FormData) {}2. The server validation
const parsed = schema.safeParse({ name: formData.get('name') });3. The client resolver
useForm({ resolver: zodResolver(schema) })4. The useTransition
const [isPending, startTransition] = useTransition();5. The Server Action call
startTransition(async () => { await createUser(formData); })6. The server error
setError('root.server', { message: result.error })7. The useActionState
const [state, formAction, pending] = useActionState(createUser, {});8. The form action
<form action={formAction}>...</form>9. The progressive enhancement
// The useActionState works without the JavaScript.10. The revalidation
// The Server Action re-validates the input.Visual
The Two Patterns
┌──────────────────────────────────────────────────────────────┐
│ THE TWO PATTERNS │
│ │
│ React Hook Form useActionState │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ The client resolver │ │ The server action │ │
│ │ The useTransition │ │ The hook's pending │ │
│ │ The setError │ │ The state.error │ │
│ │ The client features │ │ The progressive │ │
│ └─────────────────────┘ └─────────────────────┘ │
└──────────────────────────────────────────────────────────────┘The Two Validations
┌──────────────────────────────────────────────────────────────┐
│ THE TWO VALIDATIONS │
│ │
│ The client │
│ ┌─────────────────────┐ │
│ │ The zodResolver │ The UX feedback │
│ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ The Server Action │ The security boundary │
│ │ The schema.safeParse│ │
│ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ The database │ The trusted data │
│ └─────────────────────┘ │
└──────────────────────────────────────────────────────────────┘The Pending State
┌──────────────────────────────────────────────────────────────┐
│ THE PENDING STATE │
│ │
│ The React Hook Form: │
│ ┌─────────────────────┐ │
│ │ useTransition │ The isPending │
│ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ The disabled state │ The UI feedback │
│ └─────────────────────┘ │
│ │
│ The useActionState: │
│ ┌─────────────────────┐ │
│ │ The hook's pending │ The automatic pending flag │
│ └─────────────────────┘ │
└──────────────────────────────────────────────────────────────┘Summary
| Item | Value |
|---|---|
| The Server Action | The 'use server' directive |
| The revalidation | The required on the server |
| The React Hook Form pattern | The client resolver + the useTransition |
The useActionState pattern | The server-only + the progressive enhancement |
| The pending | The isPending or the pending |
| The server error | The setError('root.server') or the state.error |
Key takeaways:
- The React Hook Form and the Server Actions are the two separate layers. The
useFormvalidates on the client, and the Server Action validates on the server. The two validations are the defense in depth, and the server validation is the security boundary . - The Server Action re-validates the input. The client validation is the UX convenience, and the bypass is the reason the server validation is the requirement. The
schema.safeParseis the mechanism that keeps the invalid data out of the database . - The
useTransitionis the pending-state mechanism for the Server Action. TheisPendingis the boolean that the UI reads, and thestartTransitionis the wrapper that tracks the action’s promise . - The
setErrormaps the server error to the form. Theerrors.root.serveris the path that the server error uses, and the root error is the reason the general failure is visible . - The
useActionStateis the progressive-enhancement alternative. The hook manages the state and the pending flag, and the form works without the JavaScript. The choice between the two patterns is the client features against the progressive enhancement .
Remember: The React Hook Form and the Server Actions are the two layers. The client resolver is the UX, and the server validation is the security. The useTransition tracks the pending state, and the setError maps the server error. The useActionState is the progressive-enhancement alternative. The two validations are the defense in depth, and the depth is the reason the Server Action does not trust the client.
Stop using slow, ad-bloated tool sites! 🤮
🔎 Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)
⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free
🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!