Skip to content

getFieldState

State of the field

getFieldState: (name: string, formState?: Object) => ({isDirty, isTouched, invalid, error})

This method is introduced in react-hook-form (v7.25.0) to return individual field state. It's useful in case you are trying to retrieve nested field state in a typesafe way.

Props

NameTypeDescription
namestring

registered field name.

formState

object

This is an optional prop, which is only required if formState is not been read/subscribed from the useForm, useFormContext or useFormState.

const methods = useForm(); // not subscribed to any formState
const { error } = getFieldState('firstName', methods.formState) // It is subscribed now and reactive to error state updated

const { formState: { errors } } = useForm() // errors are subscribed and reactive to state update
getFieldState('firstName') // return updated field error state

Return

NameTypeDescription
isDirtyboolean

field is modified.

Condition: subscribe to dirtyFields.

isTouched

boolean

field has received a focus and blur event.

Condition: subscribe to touchedFields.

invalid

boolean

field is not valid.

Condition: subscribe to errors.

error

undefined | FieldError

field error object.

Condition: subscribe to errors.

Rules

  • name needs to match a registered field name.

    getFieldState('test');
    
    getFieldState('test'); // ✅ register input and return field state
    getFieldState('non-existent-name'); // ❌ will return state as false and error as undefined 
    
  • getFieldState works by subscribing to the form state update, and you can subscribe to the formState in the following ways:

    • You can subscribe at the useForm, useFormContext or useFormState. This is will establish the form state subscription and getFieldState second argument will no longer be required.

      const { register, formState: { isDirty } } = useForm()
      register('test');
      getFieldState('test'); // ✅
      
      const { isDirty } = useFormState();
      register('test');
      getFieldState('test'); // ✅
      
      const { register, formState: { isDirty } } = useFormContext();
      register('test');
      getFieldState('test'); // ✅
      
    • When form state subscription is not setup, you can pass the entire formState as the second optional argument by following the example below:

      const { register } = useForm()
      register('test');
      const { isDirty } = getFieldState('test'); // ❌ formState isDirty is not subscribed at useForm
      
      const { register, formState } = useForm()
      const { isDirty } = getFieldState('test', formState); // ✅ formState.isDirty subscribed
      
      const { formState } = useFormContext();
      const { touchedFields } = getFieldState('test', formState); // ✅ formState.touchedFields subscribed
      

Examples

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

export default function App() {
  const {
    register,
    getFieldState,
    formState: { isDirty, isValid }
  } = useForm({
    mode: "onChange",
    defaultValues: {
      firstName: ""
    }
  });

  // you can invoke before render or within the render function
  const fieldState = getFieldState("firstName");

  return (
    <form>
      <input {...register("firstName", { required: true })} />
      <p>{getFieldState("firstName").isDirty && "dirty"}</p>
      <p>{getFieldState("firstName").isTouched && "touched"}</p>
      <button type="button" onClick={() => console.log(getFieldState("firstName"))}>
        field state
      </button>
    </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