본문으로 건너뛰기

useFormState

</> useFormState: (UseFormStateProps) => FormState​

이 커스텀 훅을 사용하면 각 폼 상태를 구독하고 커스텀 훅 수준에서 리렌더링을 격리할 수 있습니다. 폼 상태 구독 범위가 독립적이므로 다른 useFormState나 useForm 훅에 영향을 주지 않습니다. 이 훅을 사용하면 크고 복잡한 폼 애플리케이션에서 리렌더링의 영향을 줄일 수 있습니다.

Props(속성)​

이름타입설명
controlObjectcontrol 객체이며 useForm이 제공합니다. FormProvider를 사용한다면 선택 사항입니다.
namestring | string[] v7.4.0부터 단일 입력 이름이나 이름 배열을 지정하거나 모든 입력의 formState 업데이트를 구독합니다.
disabledboolean = falsev7.13.0부터 구독을 비활성화하는 옵션입니다.
exactboolean = falsev7.20.0부터 이름을 정확히 일치시킬지 지정합니다. false(기본값)이면 구독한 이름이 변경된 필드 이름의 접두사이거나 그 반대일 때 구독이 실행됩니다(예: "users"를 구독하면 "users.0.name" 업데이트를 받음). v7.81.0부터 true이면 구독한 "users.0.name" 필드 자체나 상위 경로 "users.0" 또는 "users"를 setValue로 설정할 때 업데이트를 받지만, 중첩된 하위 경로가 변경될 때는 실행되지 않습니다("users" 구독은 "users.0.name" 업데이트를 받지 않음).

반환값​

이름타입설명
isDirtyboolean사용자가 입력 중 하나를 수정하면 true로 설정됩니다.
  • 중요: 폼이 dirty 상태인지 비교할 단일 기준을 훅 폼에 제공하려면 모든 입력의 defaultValues를 useForm에 지정해야 합니다.
    const {
  formState: { isDirty, dirtyFields },
  setValue
} = useForm({ defaultValues: { test: "" } })

// isDirty: true ✅
setValue('test', 'change')

// isDirty: false because there getValues() === defaultValues ❌
setValue('test', '')
  • 파일 선택을 취소할 수 있고 FileList 객체를 사용하므로 파일 타입 입력은 앱 수준에서 관리해야 합니다.
  • 사용자 정의 객체, 클래스, File 객체는 지원하지 않습니다.
dirtyFieldsobject사용자가 수정한 필드를 담은 객체입니다. 모든 입력의 defaultValues를 useForm을 통해 제공하면 라이브러리가 defaultValues.와 비교할 수 있습니다.
  • 중요: defaultValues를 useForm에 지정해 각 필드의 dirty 상태를 비교할 단일 기준을 훅 폼에 제공해야 합니다.
  • dirtyFields가 반드시 isDirty와 일치하지는 않습니다. 필드는 전체 폼이 아니라 필드 수준에서 dirty 상태로 표시됩니다. 예를 들어 필드 배열에서 항목을 추가하거나 제거하면 isDirty가 변경될 수 있지만 dirtyFields의 개별 필드는 dirty 상태로 표시되지 않을 수 있습니다. 전체 폼 상태를 확인하려면 isDirty를 사용하세요.
touchedFieldsobject사용자가 상호작용한 모든 입력을 담은 객체입니다.
defaultValuesobjectv7.37.0부터 useForm의 defaultValues에 설정했거나 reset API로 업데이트한 defaultValues 값입니다.
isSubmittedboolean폼이 제출되면 true로 설정됩니다. true 상태는 reset 메서드를 호출할 때까지 유지됩니다.
isSubmitSuccessfulboolean런타임 오류 없이 폼이 성공적으로 제출되었음을 나타냅니다.
isSubmittingboolean현재 폼을 제출하고 있으면 true, 그렇지 않으면 false입니다.
isLoadingbooleanv7.41.0부터 현재 폼이 비동기 기본값을 불러오고 있으면 true입니다.
  • 중요: 이 prop은 비동기 defaultValues에만 적용됩니다.
    const {
  formState: { isLoading }
} = useForm({
  defaultValues: async () => await fetch('/api')
})
submitCountnumber폼을 제출한 횟수입니다.
isValidboolean폼에 오류가 없으면 true로 설정됩니다.
  • setError는 즉시 isValid를 false로 만듭니다. 이 값 자체는 검증으로부터 파생되지 않으며 다음에 검증이 실행될 때(예: 다음 onChange, 제출, trigger() 호출) 덮어써집니다.
  • resolver가 없고 검증 mode가 기본값 onSubmit이라면 isValid에 실제 유효성이 반영되려면 검증이 한 번 이상 실행되어야 합니다(예: trigger() 호출이나 제출 시도).
isValidatingboolean검증 중에는 true로 설정됩니다.
validatingFieldsobjectv7.51.0부터 비동기 검증 중인 필드를 담습니다.
errorsobject필드 오류를 담은 객체입니다. 오류 메시지를 쉽게 가져오는 ErrorMessage 컴포넌트도 있습니다.
disabledbooleanv7.48.0부터 폼이 비활성화되면 true로 설정됩니다. disabled prop은 useForm에서 지정합니다.
isReadybooleanv7.56.0부터 formState 구독 설정이 준비되면 true로 설정됩니다.
예시​
import { useForm, useFormState } from "react-hook-form"

function Child({ control }) {
  const { dirtyFields } = useFormState({ control })

  return dirtyFields.firstName ? <p>Field is dirty.</p> : null
}

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

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("firstName")} placeholder="First Name" />
      <Child control={control} />

      <input type="submit" />
    </form>
  )
}