FAQ

Short answers for the most frequent adoption questions. If your issue is symptom-based, go straight to Troubleshooting.

Which package should I install: hookform-action, standalone, or core?

Setup

Use hookform-action for Next.js Server Actions. Use hookform-action-standalone for Vite/Remix/Astro/SPA apps. Use core only for custom adapters.

Is withZod required?

Validation

No. It is optional but recommended. It gives typed server validation, a standard error shape, and schema auto-detection in useActionForm.

If I already use withZod, do I still need schema in useActionForm?

Validation

Usually no. The schema is auto-detected. Pass schema only when you want to override behavior explicitly.

What is the default error contract?

Errors

Return errors as { errors: Record<string, string[]> } so field mapping works out of the box.

What is the difference between mode and validationMode?

Validation

mode is the native React Hook Form validation strategy. validationMode controls when hookform-action runs client-side schema validation.

Should submit buttons use isPending or isSubmitting?

State

Prefer isPending for UI state during the full server round-trip. isSubmitting can be narrower depending on the flow.

What is the difference between formState.errors and formState.submitErrors?

Errors

errors is RHF-ready data for rendering. submitErrors is the raw error record returned by your action.

Why are old values restored when the form mounts?

Persistence

If persistKey is set, persisted data takes precedence over defaultValues. Use scoped keys and clear persisted drafts when needed.

When is persisted state cleared automatically?

Persistence

Persisted data is cleared on successful submission. Failed submissions keep the draft for recovery.

Why is optimistic undefined?

Optimistic

You need optimisticKey and optimisticData. optimisticInitial is recommended for predictable first render behavior.

Does optimistic rollback happen automatically?

Optimistic

Yes. Rollback runs on mapped action errors and thrown exceptions. Manual rollback() is also available.

Does standalone provide formAction too?

Standalone

No. In standalone mode, you pass submit and call handleSubmit(). formAction is Next.js adapter specific.

Still blocked?

Use the troubleshooting checklist to debug by symptom: submit not firing, field errors not showing, stale persisted values, optimistic rollback issues, and upload edge cases.

Open Troubleshooting →