useForm

useForm is the main hook that you'll use to interact with RVF. It accepts a FormOpts object you use to configure the form (see below), and returns a FormApi object that you can use to interact with the form (see FormApi).

Type

function useForm<
  FormInputData extends FieldValues,
  FormOutputData,
  SubmitResponseData,
>(
  options: FormOpts<FormInputData, FormOutputData, SubmitResponseData>,
): FormApi<FormInputData>;

Usage

const form = useForm({
  defaultValues: { foo: "bar" },
  validator: myValidator,
  handleSubmit: (validatedData) => console.log(validatedData),
});

FormOpts

defaultValues

Sets the default values of the form.

For Typescript users, defaultValues is one of the most important props you'll use. The type of the object you pass here, will determine the type of the data you get when interacting with the form. For example, form.value('myField') will be typed based on the type of defaultValues.myField.

It's recommended that you provide a default value for every field in the form.

validator

A validator object created by a validation adapter such a withZod or withYup. See these docs for more details and information on how to create a validator for other validation libraries.

submitSource

Configures what RVF uses as the source of truth for form validation submission. By default, this is set to "dom", which means RVF will pull data directly out of the HTML form element. If you set this to "state", RVF will use the data stored in the form state as the source of truth. You can read more about state mode here.

handleSubmit

A function that is called when the form is submitted, if the data is valid. Depending on the submitSource you chose, this function will be called with different arguments.

"dom"

(data: FormInputData, formData: FormData, options: SubmitterOptions) => void | Promise<void>
  • data is the fully validated form data.
  • formData is the raw FormData extracted from the HTML form element.
  • options is an object that contains a few props pulled off of the submitter of the form (usually the sumbit button).

"state"

(data: FormInputData, options: SubmitterOptions) => void | Promise<void>
  • data is the fully validated form data.
  • options is an object that contains a few props pulled off of the submitter of the form (usually the sumbit button).

onBeforeSubmit

Called before when the form is submitted before any validations are run. Can be used to run custom, async validations and/or cancel the form submission. Is called with an object containing these properties:

unvalidatedData

The data inside the form before validations are run.

getValidatedData

Runs the validations and returns the validated data. If the form is not valid, it will throw an error.

getFormData

Get's the raw FormData object. This is only available when submitSource is set to dom.

cancelSubmit

Cancels the form submission and sets the submit status to error.

submitterOptions

The options passed to the form submission by the submitter. This usually comes from props passed to your submit button, but can also be passed to when calling submit manually.

onSubmitSuccess

Called after the form has been successfully submitted with whatever data was returned from the handleSubmit function. Can be useful for showing a toast message or redirecting the user to a different page. If you return a Promise from this callback, the isSubmitting state will still be true while this callback is running.

If you're using an adapter like @rvf/remix, this will be called even if you aren't using handleSubmit.

onSubmitFailure

Called when the handleSubmit function throws an error. Can be useful for showing a toast message or redirecting the user to a different page. If you return a Promise from this callback, the isSubmitting state will still be true while this callback is running.

If you're using an adapter like @rvf/remix, this will be called even if you aren't using handleSubmit.

onInvalidSubmit

Called when the user attempts to submit the form with invalid data. This is called after the first invalid field is focused. Can be useful if you want to take deeper control over how you handle invalid forms.

resetAfterSubmit

A shortcut setting that resets the form to the default values after the form has been successfully submitted. This is equivalent to calling resetForm in the onSubmitSuccess callback.

validationBehaviorConfig

Allows you to customize the validation behavior of the form. Takes three options:

  • initial - When the form first mounts, when should the validation be triggered?
  • whenTouched - Once a given field has been touched, when should the validation be triggered?
  • whenSubmitted - Once the form has been submitted unnsuccessfully, when should the validation be triggered?

action

The action prop of the form element. This will be automatically set on the form element if you use getFormProps.

id

The id of the form element. This will be automatically set on the form element if you use getFormProps.

disableFocusOnError

Disables the default behavior of focusing the first invalid field when a submit fails due to validation errors.

reloadDocument

When set to true, a valid form will be submitted natively with a full page reload. Note: This is only supported in the dom submit source.

otherFormProps

Optionally, you can pass other props to the form element here. This is primarily useful for writing custom hooks around useForm. For most use-cases, you can simply pass the props directly to the form element.

serverValidationErrors

Can be used to set the default errors of the entire form. This is most useful went integrating with server-side validation.

CAREFUL: this will cause an update every time the identity of serverValidationErrors changes. So make sure the identity of serverValidationErrors is stable.