`FormApi`

The FormApi object is the main way to interact with RVF. It's returned by useForm and can be scoped to a specific part of the form.

Prop getters

`getFormProps`

You should call this in every form you have and pass the result to your form element.

const form = useForm({
  // ...
});

return (
  <form {...form.getFormProps()}>
    <YourFormElements />
  </form>
);

Returns props that can be spread onto native form controls or thin wrappers around them. It's generally recommended to use this with native form controls. And pass any other props through this helper.

It's important that the component you spread the props into accepts the ref prop. This allows RVF to set the value of the field when setValue is called, and is used to focus the field when it has an error.

<input {...form.getInputProps("myField", { type: "number" })} />

`getControlProps`

Returns props that can be spread into controlled components to use as a field. It's important to pass the provided ref to a focusable HTML element. This allows the field to be focused when it has an error and also disables RVF's default behavior of automatically listening to changes in the field.

`getHiddenInputProps`

Returns props that can be spread into a native form control to use as a hidden field. This is useful in combination with getControlProps.

Fields and arrays

`field`

Returns a FieldApi object for the specified field. Can be called without a field name to get an field api currently in-scope form data.

`array`

Returns a FieldArrayApi object for the specified field. Can be called without a field name to get an array api currently in-scope form data.

State accessors

These functions can all be used to access the current state of the form during the render phase.

Even though these are functions, they're still tied to the render phase. Calling one of these functions in an event handler or a useEffect may not return the latest state. For those use-cases, you should use the transient api.

`name`

Returns the name of the specified field. Can be called without a field name to get the name of the field currently in-scope form data.

This can be useful if you want a typesafe way of getting the name of a field, especially if you're scoping.

`value`

Can be called with the name of a field to get the value of that field. If the FormApi is scoped to a specific part of the form, the field name is relative to the scope.

Can also be called with no arguments to get the entire form data. If the FormApi is scoped to a specific part of the form, this will be limited to the scope.

`error`

Returns the error message for the specified field, if there is one. If the FormApi is scoped to a specific part of the form, the field name is relative to the scope.

Can also be called with no arguments to get the error for the field currently in scope.

RVF takes the opinion that errors that won't be visible to a user aren't made available through this API. So you don't need to do any additional logic to determine if an error should be displayed to the user beyond checking if there's an error.

`defaultValue`

Returns the default value for the specified field. If the FormApi is scoped to a specific part of the form, the field name is relative to the scope.

Can also be called with no arguments to get the default value for the currently in-scope form data.

`touched`

Can be called with the name of a field to get whether or not that field has been touched. If the name of the field is omitted, it will return whether or not the currently scoped field has been touched.

A field has been "touched" after the user has interacted with it and moved on to another field in the form.

`dirty`

Can be called with the name of a field to get whether or not that field has been changed. If the name of the field is omitted, it will return whether or not the currently scoped field has been dirty.

A field "dirty" when it no longer matches the default value. If the user changes the value back to the default, the field will no longer be dirty.

Fields added dynamically in a field array, will always be dirty after the first change.

`formOptions`

An object that exposes a couple of the options you passed to useForm.

action
formId

If you didn't pass a formId, it will have a default value.

`formState`

Exposes some form-level state. The data in here is always based on the root-level form, even if the FormApi is scoped to a specific part of the form.

Submit status

These three props tell you about the current state of submission:

isSubmitting
- Whether or not the form is currently submitting.
hasBeenSubmitted
- Whether or not a submit has been attempted.
submitStatus
- "idle" | "submitting" | "error" | "success"

Root-level valid/dirty/touched

These tell you if any field in the form is valid, dirty, or touched.

isValid
isDirty
isTouched

All valid/dirty/touched data

Contains all the valid/dirty/touched data for every field in the form.

touchedFields
dirtyFields
fieldErrors

Transient state accessors

`transient`

The transient object contains many of the same state accessors mentioned above, except that these will not trigger rerenders and will always return the latest state. This is useful for things like event handlers.

the included state accessors are:

value
defaultValue
touched
dirty
error
formState

Example:

<button
  type="button"
  // Always logs the latest value of `myField` without causing rerenders
  onClick={() => console.log(form.transient.value("myField"))}
>
  Log value
</button>

State setters

`setValue`

Sets the value of the field with the specified name. This works for both controlled and uncontrolled fields. For uncontrolled fields, this will manually set the value of the form control using the ref returned by getInputProps.

Can also be called without a field name, to set the value of the entire form. If the FormApi is scoped to a specific part of the form, this will be limited to the scope.

`clearError`

Clears the error message for the specified field. Can be called without a field name to clear the error message for the field in scope.

`setTouched`

Manually set the touched state of the specified field. Can be called without a field name to set the touched state of the field in scope.

`setDirty`

Manually set the dirty state of the specified field. Can be called without a field name to set the dirty state of the field in scope.

`focus`

Focus the field with the specified name. This only works if the ref provided by getInputProps or getControlProp was passed to a focusable element.

`validate`

Manually validates the form. You usually don't need to do this.

`resetForm`

Resets the form to its initial state. All fields will be reset to their initial values. All touched, dirty, and validation errors will be reset. Optionally, you can provide new initial values to reset.

This will work on the root-level form, even if the FormApi is scoped to a specific part of the form.

`resetField`

Resets the field with the specified name to its initial value. This also resets any touched, dirty, or validation errors for the field. This works for both controlled and uncontrolled fields. For uncontrolled fields, this will manually set the value of the form control using the ref returned by field.

`scope`

Scopes the FormApi to a specific part of the form. See the docs on scoping for more details.

`renderFormIdInput`

Renders a hidden input that sets passes the form id to your server. This is only useful if you're supporting users who don't have JS enabled and you're returning validation errors from your server.

Helpers to subscribe to changes transiently (without causing re-renders). These should be used in an effect.

`value`

Subscribes to any change in the values of the form. Can optionally pass the name of a field to subscribe to that specific field. Returns a function that can be called to unsubscribe.

Example:

useEffect(
  () =>
    form.subscribe.value((formData) => {
      console.log(formData);
    }),
  [],
);

useEffect(
  () =>
    form.subscribe.value("myField", (myFieldData) => {
      console.log(myFieldData);
    }),
  [],
);