Initial values
In most cases you should set initialValues. They define the fields of the form and
their types, and they are used by form.reset and dirty checks:
To change values after the form was created, use one of the handlers below:
form.initialize– load a record once, sets both values and initial valuesform.setValuesandform.setFieldValue– update values, initial values stay the sameform.setInitialValues– change the values used byform.resetand dirty checksform.resetandform.resetField– go back to initial values
getValues
form.getValues() returns the current values. Use it in event handlers and callbacks.
form.values is a snapshot from the last render, it is outdated in handlers and is not
updated while the user types in uncontrolled mode:
To render a value or run an effect when it changes, see Watching values.
setValues handler
With form.setValues you can set all form values. For example, you can set values after you have received a response from the backend API:
setValues partial
form.setValues can also be used to set multiple values at once. The payload will be shallow merged with the current values state:
setFieldValue handler
The form.setFieldValue handler allows you to set the value of the field at the given path:
setFieldValue without form rerender
In uncontrolled mode, form.setFieldValue rerenders the form component
so that any input receives the new value. Pass { forceUpdate: false } to skip that render:
the input subscribed to the field updates alone, the same way as when the user types.
Use it when a field is set on every change of another field, for example to generate a
URL slug from a name:
If the input of the field is not subscribed, for example a native input element, the form
component rerenders anyway to pass the new value. The option has no effect in controlled mode.
Initialize form
form.initialize sets initialValues and values to the same value and marks the form
as initialized. Only the first call changes values: later calls keep values and initial
values as they are and only clear errors. form.initialized is true after the first call.
form.initialize is useful when you want to sync form values with backend API response:
Example with TanStack Query (react-query):
Note that form.initialize will erase all values that were set before it was called.
It is usually a good idea to set readOnly or disabled on all form fields before
form.initialize is called to prevent data loss. You can implement this with
enhanceGetInputProps:
reset handler
The form.reset handler sets values to initialValues, clears all errors and resets
touched and dirty state. With a type="reset" button, use form.onReset
as the onReset handler of the form element instead:
resetField handler
The form.resetField handler sets the value of a single field to its initial value
and clears its error and dirty state:
setInitialValues handler
The form.setInitialValues handler allows you to update initialValues after the form was initialized.
form.getInitialValues() returns the current initial values:
Values and object identity
Form values are not cloned: objects passed to initialValues, form.setValues,
form.setFieldValue and form.initialize are stored as is. Do not mutate them after
they were passed to the form.