API Reference

Canonical naming in v4: validationMode, optimisticData,submitErrors, actionResult.

Legacy aliases are still supported for backward compatibility (clientValidation, optimisticReducer, serverErrors, lastResult, setServerError, clearPersisted).

useActionForm (Next.js)

import { useActionForm } from 'hookform-action'

Bridges React Hook Form with a Next.js Server Action.

function useActionForm<TFieldValues, TResult>(
  action: ServerAction<TResult>,
  options?: UseActionFormOptions<TFieldValues, TResult>
): UseActionFormReturn<TFieldValues, TResult>

Options

Option	Type	Default	Description
defaultValues	DefaultValues<T>	—	Initial form values.
mode	Mode	'onSubmit'	RHF validation mode.
persistKey	string	—	Enables sessionStorage persistence.
persistDebounce	number	300	Debounce interval (ms) for persistence.
errorMapper	ErrorMapper<T>	defaultErrorMapper	Custom error extractor.
onSuccess	(result) => void	—	Called after successful submission.
onError	(result \| Error) => void	—	Called on error.
schema	ZodSchema	—	Zod schema for client-side validation. Auto-detected from withZod.
validationMode	ClientValidationMode	'onSubmit'	'onChange' \| 'onBlur' \| 'onSubmit'.
optimisticKey	string	—	Enables optimistic UI.
optimisticData	(current, formData) => T	—	Reducer for optimistic state.
optimisticInitial	T	—	Initial data for optimistic state.

useActionForm (Standalone)

import { useActionForm } from 'hookform-action-standalone'

v4Same API, but takes an options object with submit instead of a Server Action.

function useActionForm<TFieldValues, TResult>(
  options: UseStandaloneActionFormOptions<TFieldValues, TResult>
): UseStandaloneActionFormReturn<TFieldValues, TResult>

Additional Options

Option	Type	Description
submit	(data: T) => Promise<TResult>	Required. The async function that handles form submission. Replaces the Server Action argument.

All other options (defaultValues, schema, validationMode,persistKey, optimisticKey, etc.) are identical to the Next.js version. The return type is the same except there is no formAction property.

useActionFormCore

import { useActionFormCore } from 'hookform-action-core/core'

v4Framework-agnostic core hook. Adapters (Next.js, standalone) wrap this. Use directly only for building custom adapters.

function useActionFormCore<TFieldValues, TResult>(
  submit: SubmitFunction<TFieldValues, TResult>,
  options?: UseActionFormCoreOptions<TFieldValues, TResult>
): UseActionFormCoreReturn<TFieldValues, TResult>

Return Value

Returns everything from React Hook Form's useForm, plus:

Need a full timeline and state-by-state guide? See Submit Lifecycle.

Property	Type	Description
handleSubmit	(onValid?) => handler	Enhanced submit handler.
formState.isSubmitting	boolean	Submit-in-progress flag (RHF + internal action state). Prefer `isPending` for UX locking/loading.
formState.isPending	boolean	True while transition/request is pending. Primary state for disabled buttons and spinners.
formState.isSubmitSuccessful	boolean	True when the last completed submit succeeded (no field errors).
formState.submitErrors	FieldErrorRecord \| null	Structured field errors from validation/client mapping.
formState.actionResult	TResult \| null	Full result from the last completed action response (use with success guards).
setSubmitError	(field, msg) => void	Manually set a server error on a field.
persist	() => void	Manually persist to sessionStorage.
clearPersistedData	() => void	Clear persisted data.
formAction	(FormData) => Promise	Next.js only. Direct form action for `<form action={…}>`.
optimistic	OptimisticState<T> \| undefined	Optimistic state with data, isPending, rollback().

<Form />

Headless wrapper providing RHF FormContext. Works with both adapters.

<Form
  form={formReturn}
  onValid={(data) => console.log(data)}
  className="space-y-4"
>
  <input {...form.register('email')} />
  <button type="submit">Submit</button>
</Form>

Props

Prop	Type	Description
form	UseActionFormReturn \| UseActionFormCoreReturn	Return value from useActionForm (any adapter).
onValid	(data) => void	Optional callback before action is called.
...rest	HTMLFormAttributes	All standard <form> attributes.

Utilities

Persistence Helpers

import {
  loadPersistedValues,
  savePersistedValues,
  clearPersistedValues,
} from 'hookform-action-core'

const data = loadPersistedValues<MyForm>('my-key')
savePersistedValues('my-key', { email: 'a@b.com' })
clearPersistedValues('my-key')

withZod

Wraps a Server Action with Zod validation. The schema is auto-detected on the client.

import { withZod } from 'hookform-action-core/with-zod'
// or: import { withZod } from 'hookform-action-core/zod'

const action = withZod(schema, async (data) => {
  // data is fully typed
  return { success: true }
})

defaultErrorMapper

import { defaultErrorMapper } from 'hookform-action-core'

const customMapper = (result) => {
  const zodErrors = defaultErrorMapper(result)
  if (zodErrors) return zodErrors
  // Handle custom format...
  return null
}

Plugin System (Internal)

v4Internal plugin architecture for extending useActionFormCore. Not yet part of the public API.

interface ActionFormPlugin<TFieldValues, TResult> {
  name: string
  onBeforeSubmit?: (data) => boolean | Promise<boolean>
  onSuccess?: (result, data) => void
  onError?: (error, data) => void
  onMount?: () => (() => void) | void
}

Lifecycle	When it runs
onBeforeSubmit	Before submit. Return `false` to block submission.
onSuccess	After successful submission (no field errors).
onError	After failed submission or thrown error.
onMount	On mount. Return cleanup function for unmount.

Packages

Package	Version	Purpose
hookform-action-core	4.0.3	Core + Next.js adapter (backward-compatible)
hookform-action	4.0.3	Standalone Next.js adapter package
hookform-action-standalone	4.0.3	Adapter for Vite, Remix, Astro, SPAs
hookform-action-devtools	4.0.3	Floating debug panel (FormDevTool)