Chapter 18: resetField

Core Idea

resetField(name, options?) resets one registered field's value and state (error, dirty, touched) independently, without touching the rest of the form.

Key Concepts

• name must match a registered field — an unregistered name fails silently to find the input.
• Default behavior: reverts to the field's defaultValue; re-evaluates isValid (unless keepError: true) and isDirty (unless keepDirty: true).
• keepError / keepDirty / keepTouched: preserve that specific piece of the field's state instead of clearing it.
• defaultValue option: when provided, the field is updated to this value and its defaultValue is updated to match (so future resets/dirty-comparisons use the new baseline); when omitted, the field just reverts to its existing defaultValue. Must not be undefined.

Code Examples

resetField("firstName")                              // revert to defaultValue, clear error/dirty
resetField("firstName", { keepError: true })          // revert value, keep the error showing
resetField("firstName", { keepDirty: true })           // revert value, keep dirtyFields state
resetField("firstName", { defaultValue: "New" })       // set a new value AND a new baseline defaultValue

• What it demonstrates: the range from a full field reset to a targeted, state-preserving one.

Anti-patterns

• Calling resetField on a name that was never registered: the call fails to find the field — always resetField after register, on the exact same name.
• Passing defaultValue: undefined: not supported — omit the option entirely to fall back to the existing default instead.

Key Takeaways

1. resetField is the single-field version of reset — reach for it instead of a full-form reset when only one field needs to go back to baseline.
2. Supplying defaultValue doesn't just set the value once — it moves the field's baseline for future dirty comparisons too.

Connects To

• useform-reset: the whole-form equivalent.
• useform-formstate: where the resulting isDirty/errors/touchedFields changes are observed.