Chapter 16: reset

Core Idea

reset(values?, options?) resets the entire form — values, field refs, and subscriptions — with granular keepX flags to preserve specific pieces of state across the reset.

Key Concepts

• values: object (ideally the full set, not partial) or a callback (currentValues) => nextValues (7.36.0+) to reset to.
• Calling reset(values) updates defaultValues: unless keepDefaultValues is set — a later reset()/reset({}) with no values then resets to that last-provided values, not the original useForm defaults.
• keepDirty / keepDirtyValues: keepDirty preserves dirtyFields/isDirty state itself (not input values); keepDirtyValues (7.31.0+) preserves dirty fields and their current values while non-dirty fields update to the new values — requires dirtyFields to be subscribed.
• keepValues: input values stay unchanged.
• keepDefaultValues: keeps the original useForm defaults instead of adopting the new values; isDirty/dirtyFields recompute against the new values vs. those original defaults.
• keepErrors / keepIsSubmitted / keepIsSubmitSuccessful / keepTouched / keepIsValidating / keepIsValid / keepSubmitCount: preserve the named formState slice instead of clearing it.
• keepFieldsRef (7.60.0+): preserves internal field references so resetting values doesn't unmount/remount the actual input elements.
• Recommended for submit-then-reset: call reset() inside a useEffect watching formState.isSubmitSuccessful, not directly inside the onSubmit callback — execution order matters.

Code Examples

reset(result) // full async reset, e.g. after fetching saved values

reset({ firstName: "bill" }, { keepErrors: true, keepDirty: true }) // partial reset, preserve some state

reset((formValues) => ({ ...formValues, lastName: "test" })) // callback form

• What it demonstrates: the three common reset shapes — full replace, partial replace with state preserved, and a functional update.

useEffect(() => {
  if (formState.isSubmitSuccessful) {
    reset({ something: "" })
  }
}, [formState.isSubmitSuccessful, reset])

• What it demonstrates: the recommended submit-then-reset pattern, driven by formState.isSubmitSuccessful in an effect rather than called synchronously inside onSubmit.

Reference Tables

Option	Preserves
keepErrors	error state (not guaranteed to survive further user action)
keepDirty	dirty state flags (not input values)
keepDirtyValues	dirty fields' state + values; only non-dirty fields adopt new values
keepValues	current input values entirely
keepDefaultValues	the original useForm defaultValues
keepIsSubmitted / keepIsSubmitSuccessful / keepSubmitCount	submission-history flags
keepTouched	isTouched
keepIsValidating	in-flight validation state
keepIsValid	isValid (temporarily, until next user action)
keepFieldsRef	internal field refs (no unmount/remount)

Anti-patterns

• Calling reset() synchronously inside onSubmit: execution order can bite you — gate it on formState.isSubmitSuccessful in a useEffect instead.
• Resetting with only a partial values object without keepDefaultValues/awareness that it becomes the new baseline: subsequent no-argument resets return to that partial set, not the original defaults.

Key Takeaways

1. reset(values) becomes the new baseline for future resets unless keepDefaultValues is set.
2. keepDirty and keepDirtyValues are different things — one preserves flags, the other preserves both flags and the actual dirty values.
3. Prefer the useEffect + isSubmitSuccessful pattern for reset-after-submit.

Connects To

• useform-formstate: the isSubmitSuccessful flag driving the recommended reset pattern.
• useform-resetfield / useform-resetdefaultvalues: narrower alternatives — one field, or just the defaults baseline.
• usefieldarray: reset with a values object containing array data replaces the whole array too.