Resetting a Form

Since 3.0.0, gform-react supports a native form reset. A <button type="reset"> inside a GForm - or calling form.reset() on the element - restores every field to the value it started with, and the controlled inputs re-render to match. File inputs reset too, so the DOM and the form store never drift apart.

Reset to initial values: <button type="reset">

Drop a native reset button inside the form. gform intercepts the reset, restores each field's initial state from the snapshot it took when the field registered - value, error, errorText, touched, and dirty - and the inputs follow:

<GForm validators={validators} onSubmit={handleSubmit}>
  <GInput formKey="name" value="Ada" required />
  <GInput formKey="email" type="email" required />
 
  <button>Save</button>
  <button type="reset">Reset</button>
</GForm>

The baseline a reset restores to is, in order:

1. the field's value prop, if it has one;
2. otherwise the value seeded by onInit (gform re-snapshots the baseline after onInit runs, so an edit form resets to the loaded record, not to empty);
3. otherwise empty.

You don't need a button at all - calling reset() on the form element works the same way, which is handy after a successful submit:

onSubmit={(state, e) => {
  e.preventDefault();
  save(state.toRawData());
  e.currentTarget.reset(); // back to initial values for the next entry
}}

Running code after a reset: onReset

GForm takes an onReset?: (state, e) => void prop that fires after the fields have been restored - use it for side effects like clearing a server message or refocusing the first field:

<GForm
  validators={validators}
  onReset={(state, e) => {
    setServerError(null);
    e.currentTarget.querySelector("input")?.focus();
  }}
>

gform handles preventDefault() internally, so the native page reset never fires - you only get the store restore plus your onReset callback.

Clear or set values in place: dispatchChanges

A native reset always returns to the initial values. When you instead want to clear to empty, or set fields to specific values without tearing anything down (keeping focus, scroll, and the same DOM node), use the form-level dispatchChanges to write every field at once. Include error/errorText/touched/dirty so a cleared field also looks pristine - a plain dispatchChanges doesn't re-validate, so a stale error would otherwise linger:

const pristine = { value: "", error: false, errorText: "", touched: false, dirty: false };
 
state.dispatchChanges({
  firstName: pristine,
  lastName: pristine,
  email: pristine,
});

The same call sets values to anything else - handy for "restore defaults" or loading a record to edit:

state.dispatchChanges({
  firstName: { value: "Ada" },
  email: { value: "ada@example.com" },
});

Reset and re-mount: change the key

If you want to throw the entire form instance away - clearing every bit of internal state, not just the field values - change a React key on <GForm>. React mounts a fresh instance that re-seeds from each field's value prop. This is heavier than a native reset (it remounts the DOM and loses focus/scroll), so reach for it only when you specifically want a clean instance:

const [formId, setFormId] = useState(0);
 
<GForm key={formId} validators={validators}>
  {/* … fields with their initial `value`s … */}
</GForm>
 
<button type="button" onClick={() => setFormId((n) => n + 1)}>Hard reset</button>

Try it live

Name starts as "Ada". Edit the fields, then: Reset to initial snaps them back to "Ada" / empty via the native reset; Clear empties both in place; and a successful Submit calls form.reset() to ready the form for the next entry.

See Dispatching Changes for more on writing form state and GForm for seeding initial values with onInit.