Skip to content

useFormState

Subscribe to form state update

useFormState: ({ control: Control }) => FormState

This custom hook allows you to subscribe to each form state, and isolate the re-render at the custom hook level. It has its scope in terms of form state subscription, so it would not affect other useFormState and useForm. Using this hook can reduce the re-render impact on large and complex form application.

Props

The following table contains information about the arguments for useFormState.

NameTypeDescription
controlobjectcontrol object provided by useForm. It's optional if you are using FormContext.
namestring | string[]Provide a single input name, an array of them, or subscribe to all inputs' formState update.
disabledboolean = false

Option to disable the subscription.

exactboolean = false

This prop will enable an exact match for input name subscriptions.

Return

NameTypeDescription
isDirtyboolean

Set to true after the user modifies any of the inputs.

  • Make sure to provide all inputs' defaultValues at the useForm, so hook form can have a single source of truth to compare whether the form is dirty.

    const {
      formState: { isDirty, dirtyFields },
      setValue,
    } = useForm({ defaultValues: { test: "" } });
    
    // isDirty: true
    setValue('test', 'change')
     
    // isDirty: false because there getValues() === defaultValues
    setValue('test', '') 
    
  • File typed input will need to be managed at the app level due to the ability to cancel file selection and FileList object.

dirtyFieldsobject

An object with the user-modified fields. Make sure to provide all inputs' defaultValues via useForm, so the library can compare against the defaultValues.

Dirty fields will not represent as isDirty formState, because dirty fields are marked field dirty at field level rather the entire form. If you want to determine the entire form state use isDirty instead.

touchedFieldsobjectAn object containing all the inputs the user has interacted with.
defaultValuesobject

The value which has been set at useForm's defaultValues or updated defaultValues via reset API.

isSubmittedbooleanSet to true after the form is submitted. Will remain true until the reset method is invoked.
isSubmitSuccessfulboolean

Indicate the form was successfully submitted without any Promise rejection or Error been thrown within the handleSubmit callback.

isSubmittingbooleantrue if the form is currently being submitted. false otherwise.
submitCountnumberNumber of times the form was submitted.
isValidboolean
Set to true if the form doesn't have any errors.
  • isValid is affected by mode at useForm. This state is only applicable with onChange, onTouched, and onBlur mode.

  • setError has no effect on isValid formState, isValid will always derived via the entire form validation result.

isValidatingbooleanSet to true during validation.
errorsobjectAn object with field errors. There is also an ErrorMessage component to retrieve error message easily.

Rules

Returned formState is wrapped with Proxy to improve render performance and skip extra computation if specific state is not subscribed, so make sure you deconstruct or read it before render in order to enable the subscription.

const { isDirty } = useFormState(); // ✅
const formState = useFormState(); // ❌ should deconstruct the formState      

Examples

import * as React from "react";
import { useForm, useFormState } from "react-hook-form";

export default function App() {
  const { register, handleSubmit, control } = useForm({
    defaultValues: {
      firstName: "firstName"
    }
  });
  const { dirtyFields } = useFormState({
    control
  });
  const onSubmit = (data) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("firstName")} placeholder="First Name" />
      {dirtyFields.firstName && <p>Field is dirty.</p>}
      
      <input type="submit" />
    </form>
  );
}

Thank you for your support

If you find React Hook Form to be useful in your project, please consider to star and support it.

Edit