v4.0.x|Docs Home

React Hook Form + server submit flows, without boilerplate.

Connect React Hook Form to Server Actions or submit functions with end-to-end types, Zod mapping, optimistic UI, and persistence for multi-step flows.

Pick your adapter. Keep one API. Ship production forms faster.

Build your first form in 2 minutes Open Standalone Quick Start Read full API

Next.js Server ActionsViteRemixAstro

Quick Start In 3 Steps

From install to first submit in around two minutes.

New here? Start with login example.

Step 1

Install the adapter for your stack

npm install hookform-action react-hook-form zod

npm install hookform-action-standalone react-hook-form zod

Step 2

Wrap server logic with withZod

export const action = withZod(schema, async (data) => {
  return { success: true };
});

Step 3

Call useActionForm and submit

const form = useActionForm(action, {
  validationMode: 'onChange',
});
<form onSubmit={form.handleSubmit()} />

Manual Wiring vs hookform-action

Same primitives, less glue code. You keep RHF and Zod control, but remove repeated submit-flow plumbing.

Concern	Manual	hookform-action
Type safety from schema to submit handler	Manual casting and duplicated generic types	Inference from withZod schema to useActionForm
Server validation errors to RHF fields	Parse fieldErrors and loop setError() per field	Automatic mapping through default error mapper
Pending submit state	Wire useTransition separately from RHF formState	formState.isPending available in the hook result
Optimistic UI with rollback	Build custom useOptimistic wiring per form	Enable optimisticData and optimisticKey options
Multi-step persistence	Custom sessionStorage effects and debounce logic	Built-in persistKey and persistDebounce options
Cross-framework submit flow	Rewrite integration for each stack	Same API in Next.js and standalone adapters

Before (manual)

const result = await action(values);
if (result.errors) {
  for (const [field, messages] of Object.entries(result.errors)) {
    setError(field as keyof Fields, { message: messages[0] });
  }
}

After (hookform-action)

const { handleSubmit, formState: { errors, isPending } } =
  useActionForm(action, { validationMode: 'onChange' });

<form onSubmit={handleSubmit()} />;

-1 layer

single integration API for submit flows

+1 schema

server and client stay aligned

-N bugs

less custom wiring to maintain per form

Feature Clusters

Built on top of RHF. No lock-in, only less repetition.

RHF + server submit flow

Integration Layer

•Single hook for React Hook Form and server submit handlers
•Schema-driven types from withZod into client usage
•Automatic data and error shape handling for common server responses

Fast forms without custom plumbing

State And UX

•Pending state aligned with concurrent React submit flow
•Optimistic updates with rollback support
•Session persistence for multi-step and long forms

Fits existing architecture

Extensibility

•Next.js adapter and standalone adapter with matching API
•Lifecycle callbacks for success and error integrations
•DevTools package for live form and submission inspection

Built for real projects

Production Readiness

•ESM + CJS outputs and tree-shakeable package structure
•MIT licensed monorepo with separate package changelogs
•Automated test coverage in core and standalone adapters

Examples You Can Copy

Use these as your onboarding path: beginner to advanced submit flows.

Browse all recipes

Next.js Server ActionsBeginner

Login With Server Errors

Typed login form with field-level server validation and pending button state.

Open login example →

Next.js + optimistic UICommon

Optimistic Todo Submit

Immediate UI updates during submit, with rollback behavior when server fails.

Open optimistic example →

Next.js + persistenceAdvanced

Multi-Step Wizard

Persist form progress across reloads and steps with a shared persist key.

Open wizard example →

Vite / Remix / AstroCommon

Standalone Submit Flow

Same API using submit functions with fetch, axios, or RPC endpoints.

Open standalone recipe →

Mental Model

One schema, one action, one form hook.

1. Define schema and server handler with withZod.
2. Pass action (or submit function) into useActionForm.
3. Render standard RHF fields and call handleSubmit().
4. Let the hook manage pending, error mapping, optimistic state, and persistence.

Architecture

withZod(schema, handler)
          |
          v
   useActionFormCore
      /        \
     v          v
hookform-action   hookform-action-standalone
      \          /
       v        v
   hookform-action-devtools

Compatibility

Dependency	Minimum	Notes
React	18.0+	React 19 recommended for native useOptimistic behavior.
React Hook Form	7.50+	Required peer dependency.
Zod	3.22+	Optional, recommended for withZod and typed validation flow.
Next.js	14.0+	Only required for the Next.js adapter package.

Upgrade Notes

Current package line is 4.0.x. Before upgrading, check package changelogs to confirm API notes and migration details for your adapter.

Open Next.js adapter changelog →Open standalone adapter changelog →Open API reference →

Maturity And Trust Signals

Production-focused signals to reduce adoption risk.

Versioned Packages

v4.0.x adapters and core published independently.

MIT License

Open source license with permissive commercial usage.

Automated Tests

Core and standalone packages include Vitest test suites.

CI In GitHub Actions

Repository checks run in public workflow pipelines.

Changelogs

Each package has explicit release notes and history.

SemVer Workflow

Changesets + release process managed in monorepo scripts.

View CI pipeline View repository

FAQ

Is this too much abstraction over React Hook Form?

No. You still use RHF primitives directly. The library removes repeated glue code between RHF, server submit handlers, and schema validation.

Should I use it for small forms?

If your form never hits a server, native RHF is often enough. The value appears when multiple forms share server submit and validation flows.

Can I use it outside Next.js?

Yes. Use hookform-action-standalone for Vite, Remix, Astro, or any React app with async submit functions.

Do I need Zod?

Zod is optional, but recommended. withZod unlocks end-to-end type inference and automatic error mapping without duplicated schema setup.

Install And Ship Your First Form Today

Start with the adapter that matches your stack and move from setup to running form quickly.

npm install hookform-action react-hook-form zod

npm install hookform-action-standalone react-hook-form zod

Open quick start example Read API reference