Advanced

Practical guides for building accessible, reusable, and performant forms

View Markdown Open in ChatGPT Open in Claude

Explore practical patterns for reusable forms, performance, custom validation, testing, and complex workflows. For a learning path and examples organized by task, start with Guides. For function signatures and options, see the API reference.

Find a pattern for your task

I want to…	Start here
Edit an existing record without losing user changes	Editing saved data
Display API validation errors and allow retries	Handling server errors
Show fields based on another input	Conditional fields
Avoid re-rendering a large form on every keystroke	Isolating form subscriptions
Make labels, errors, and focus work together	Accessibility
Collect data across several steps	Multi-step forms
Share form methods with nested components	Connect Form
Use a component library or schema validator	Integrations
Test validation and submission	Testing forms
Submit with React 19 and Next.js	Server Actions

Upgrading an existing project? Follow the Migrate to v8 guide.

Editing saved data

Use defaultValues as the starting point for an edit form. They are cached when the form mounts: passing a different object on a later render does not load a different record. Fetch the record in a parent, handle loading and errors there, and render the form once the data is ready.

import { useForm } from "react-hook-form"

type Profile = { id: string; name: string; email: string }
type ProfileFields = Pick<Profile, "name" | "email">

export function ProfileEditor({
  profile,
  saveProfile,
}: {
  profile: Profile
  saveProfile: (values: ProfileFields) => Promise<void>
}) {
  const {
    register,
    handleSubmit,
    reset,
    setError,
    clearErrors,
    formState: { errors, isDirty, isSubmitting },
  } = useForm<ProfileFields>({
    defaultValues: { name: profile.name, email: profile.email },
  })

  const onSubmit = async (values: ProfileFields) => {
    clearErrors("root.server")
    try {
      await saveProfile(values)
    } catch {
      setError("root.server", {
        message: "Could not save your changes. Please try again.",
      })
    }
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <label htmlFor="profile-name">Name</label>
      <input id="profile-name" {...register("name")} />
      <label htmlFor="profile-email">Email</label>
      <input id="profile-email" type="email" {...register("email")} />
      {errors.root?.server && <p role="alert">{errors.root.server.message}</p>}
      <button type="submit" disabled={!isDirty || isSubmitting}>
        {isSubmitting ? "Saving…" : "Save changes"}
      </button>
      <button type="button" disabled={isSubmitting} onClick={() => reset()}>
        Discard changes
      </button>
    </form>
  )
}

The parent supplies saveProfile; it should reject when the request fails. This example keeps the edited values after saving. If the server returns normalized values and you want the saved record to become the new baseline, call reset(savedProfile) when that successful response arrives, outside the submit handler. See the reset rules for submission-state timing.

When switching between records, render <ProfileEditor key={profile.id} ... /> with the real props to start a fresh form for each record. Decide whether to prompt about unsaved changes before switching.

For background refetches of the same record, choose whether to replace the user's edits. A deliberate reset(freshValues) replaces all values and establishes a new baseline. reset(freshValues, { keepDirtyValues: true }) updates untouched fields while preserving edited fields; subscribe to formState.dirtyFields when using this option. Do not run an unconditional reset on every render or on every recreated data object.

If the form itself owns the initial request, async default values are another option. Handle a rejected request, show loading feedback, and remember that this initializer runs once per mount. Use the reactive values option when external data should continue updating the form, with an explicit policy for preserving user edits.

Handling server errors

Client validation provides quick feedback. The server must also validate submitted values. Use setError for a specific field, and root.server for a request failure that does not belong to one input.

This example expects POST /api/profile to return a successful HTTP status after saving, or HTTP 422 with { "errors": { "email": "This email is already in use." } }. Implement that endpoint in your application and adjust the response mapping to its contract.

import { useState } from "react"
import { useForm } from "react-hook-form"

type FormValues = { email: string }

export default function EmailForm() {
  const [saved, setSaved] = useState(false)
  const {
    register,
    handleSubmit,
    setError,
    clearErrors,
    formState: { errors, isSubmitting },
  } = useForm<FormValues>({ defaultValues: { email: "" } })

  const onSubmit = async (values: FormValues) => {
    setSaved(false)
    clearErrors("root.server")

    try {
      const response = await fetch("/api/profile", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(values),
      })

      if (response.status === 422) {
        const result: { errors?: { email?: string } } = await response.json()
        if (typeof result.errors?.email === "string") {
          setError(
            "email",
            { type: "server", message: result.errors.email },
            { shouldFocus: true }
          )
          return
        }
      }

      if (!response.ok) throw new Error("Save failed")
      setSaved(true)
    } catch {
      setError("root.server", {
        type: "server",
        message: "We couldn't save your email. Please try again.",
      })
    }
  }

  return (
    <form noValidate onSubmit={handleSubmit(onSubmit)}>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        aria-invalid={!!errors.email}
        aria-describedby={errors.email ? "email-error" : undefined}
        {...register("email", {
          required: "Enter your email address.",
          onChange: () => setSaved(false),
        })}
      />
      {errors.email && (
        <p id="email-error" role="alert">
          {errors.email.message}
        </p>
      )}
      {errors.root?.server && <p role="alert">{errors.root.server.message}</p>}
      {saved && <p role="status">Email saved.</p>}
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Saving…" : "Save email"}
      </button>
    </form>
  )
}

Return the request promise from your submit handler, or await it as above, so isSubmitting covers the request. fetch does not reject on HTTP error responses, so check response.ok. Keep the inputs available after failure so the user can correct a value and retry.

shouldFocus needs a registered input ref. Keep that input enabled if you want to focus it after a server error. Only map known field names from the response, rather than treating every server key as a valid form path.

This example sets the success message only after a successful HTTP response. React Hook Form cannot interpret your API response: catching a failed request without reporting an error can leave the handler looking successful. Check the response and surface failures explicitly.

Conditional fields

Use useWatch to show an input based on another value. Decide what should happen to its data when it disappears: retain it for a later step, or remove it from the submission.

import { useForm, useWatch } from "react-hook-form"

type FormValues = { accountType: "personal" | "business"; company?: string }

export default function AccountForm() {
  const {
    control,
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<FormValues>({
    defaultValues: { accountType: "personal" },
    shouldUnregister: true,
  })
  const accountType = useWatch({ control, name: "accountType" })

  return (
    <form noValidate onSubmit={handleSubmit((values) => console.log(values))}>
      <label htmlFor="account-type">Account type</label>
      <select id="account-type" {...register("accountType")}>
        <option value="personal">Personal</option>
        <option value="business">Business</option>
      </select>
      {accountType === "business" && (
        <div>
          <label htmlFor="company">Company name</label>
          <input
            id="company"
            aria-invalid={!!errors.company}
            aria-describedby={errors.company ? "company-error" : undefined}
            {...register("company", { required: "Enter your company name." })}
          />
          {errors.company && (
            <p id="company-error" role="alert">
              {errors.company.message}
            </p>
          )}
        </div>
      )}
      <button type="submit">Continue</button>
    </form>
  )
}

Here shouldUnregister: true removes the company value when its input unmounts. Switching back to a business account starts that field again. The default, false, retains values after unmounting, which can be useful in a wizard. Hiding an input with CSS leaves it mounted and does not unregister it.

With a schema resolver, express the same condition in the schema: require company only for business accounts. Unregistering an input does not rewrite your schema. For reordered field arrays, review the Controller rules before applying shouldUnregister, because reordering can unmount and remount inputs.

Isolating form subscriptions

Subscribe where a value is displayed. Calling watch() at the top of a large form makes that component re-render for every value change. Move small reactive pieces into child components so a counter or error message can update without re-rendering the entire form through a root subscription.

Need	API
Render a field value or a derived preview	`useWatch` in the consuming component
Render errors, dirty state, or submission state	`useFormState` near that UI
Read values once in an event handler	`getValues`
Observe changes without rendering UI	`subscribe`, with cleanup

import { useForm, useFormState, useWatch, type Control } from "react-hook-form"

type FormValues = { biography: string }

function BiographyFeedback({ control }: { control: Control<FormValues> }) {
  const biography = useWatch({ control, name: "biography" })
  const { errors } = useFormState({ control, name: "biography" })

  return (
    <div>
      <p id="biography-count">{biography.length} / 200 characters</p>
      <p id="biography-error" role="alert">
        {errors.biography?.message}
      </p>
    </div>
  )
}

export default function BiographyForm() {
  const { register, control, handleSubmit } = useForm<FormValues>({
    defaultValues: { biography: "" },
    mode: "onBlur",
  })

  return (
    <form onSubmit={handleSubmit((values) => console.log(values))}>
      <label htmlFor="biography">Biography</label>
      <textarea
        id="biography"
        aria-describedby="biography-count biography-error"
        {...register("biography", {
          maxLength: { value: 200, message: "Use 200 characters or fewer." },
        })}
      />
      <BiographyFeedback control={control} />
      <button type="submit">Save biography</button>
    </form>
  )
}

Only BiographyFeedback subscribes to biography changes. The parent can still re-render for other React reasons; this pattern removes the subscription that would otherwise update it on each keystroke. Measure before adding memoization, and use mode: "onChange" only when validation on every change is useful to the user. For context-based forms, see FormProvider performance.

Accessibility (A11y)

Give every input a visible label, describe errors in text, and connect the error message to its input. Keep the registered ref attached so React Hook Form can focus the first invalid field on submission.

import { useForm } from "react-hook-form"

type FormValues = { name: string }

export default function AccessibleForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<FormValues>({ defaultValues: { name: "" } })

  return (
    <form noValidate onSubmit={handleSubmit((values) => console.log(values))}>
      <label htmlFor="name">Name</label>
      <p id="name-hint">Use the name you want displayed on your profile.</p>
      <input
        id="name"
        aria-invalid={!!errors.name}
        aria-describedby={errors.name ? "name-hint name-error" : "name-hint"}
        {...register("name", {
          required: "Enter your name.",
          maxLength: { value: 30, message: "Use 30 characters or fewer." },
        })}
      />
      {errors.name && (
        <p id="name-error" role="alert">
          {errors.name.message}
        </p>
      )}
      <button type="submit">Save profile</button>
    </form>
  )
}

noValidate disables the browser's validation messages so this example consistently uses the messages registered with React Hook Form. It does not disable React Hook Form's validation.

aria-invalid exposes the invalid state, aria-describedby connects hints and errors, and role="alert" announces a newly displayed error. The exact announcement varies by browser and assistive technology. Do not rely on color alone, and test keyboard navigation and error focus in your actual UI. For custom controlled inputs, forward field.ref to the focusable element.

Wizard Form / Funnel

For steps that stay mounted under one parent, a single useForm instance with FormProvider can share values across the steps. Validate the current step with trigger before advancing. Use separate forms and shared storage when each step is a different route or needs its own submission boundary.

The route-based example below uses little state machine. React context, a parent component, or your existing state library can also hold the draft; an additional library is optional. Initialize each step from the stored draft so going back restores the user's previous answers.

Step 1: Set up your routes and store.

Find a pattern for your task

Editing saved data

Handling server errors

Conditional fields

Isolating form subscriptions

Accessibility (A11y)

Wizard Form / Funnel

Smart Form Component

Error Messages

Register

Optional Chaining

Lodash get

Connect Form

FormProvider Performance

Controlled mixed with Uncontrolled Components

Custom Hook with Resolver

Working with virtualized lists

Testing Form

Resolving act warning during test

Transform and Parse

Server Actions / useActionState

Registering Opaque Types

Lodash `get`