useForm 일반 props

mode
폼 제출 전 사용자의 액션에 따라 유효성 검사 타이밍을 결정.

reValidateMode
폼 제출 후 오류값 재검증 시 유효성 검사를 트리거할 사용자의 액션.

defaultValues
기본값(초기 렌더링 시 캐싱됨)
이후에 비동기로 데이터 조작시에는 values나 reset 함수 사용

values
Form 값을 업데이트하기 위한 반응형(Controlled) 값
외부 상태(예: API 데이터)가 변경될 때 폼 값을 자동으로 동기화하고 싶을 때 사용

errors
유효성 검사가 실패한 필드의 오류 정보(type, message 등)를 담고 있는 객체.
중요 : 오류 객체 참조 - stable를 유지하여 무한 재렌더링 방지

resetOptions
values나 defaultValues가 업데이트되어 폼 값이 새롭게 바뀔 때, 기존 폼 상태(에러, 방문 기록 등)의 유지 여부를 설정하는 옵션.

criteriaMode
모든 검증 오류를 표시하거나 한 번에 하나씩 표시

shouldFocusError
제출 시 에러가 난 첫 필드로 포커스 자동 이동 활성화하거나 비활성화

delayError
오류가 나타나는 시점을 밀리초(ms) 단위로 지연시킴.
사용자가 타이핑하는 동안 에러 메시지가 너무 빨리 깜빡이는 걸 방지.

validate
사용자 정의 유효성 검사 함수.
(기본 제공되는 required, pattern 외에 직접 로직을 짜서 검증할 때 사용)

shouldUseNativeValidation
브라우저 내장 form constraint API 사용

shouldUnregister
컴포넌트가 화면에서 사라질(Unmount) 때 해당 필드 값도 폼 데이터에서 삭제할지 결정.
기본값 = false라 사라져도 값은 유지됨.

progressive
Form component를 사용할 때 기본 양식 제출 점진적인 향상(progressive enhancemen) 활성화.

disabled
전체 폼 필드를 한 번에 비활성화하며, 이때 해당 필드들은 유효성 검사에서 제외됨.

useForm 스키마 검증 Props

resolver
스키마 기반의 외부 검증 라이브러리(Zod, Yup, Joi 등)를 React Hook Form과 연결하는 함수

context
스키마 검증 시 외부 데이터를 참조할 수 있게 넘겨주는 객체.
폼 내부 데이터가 아닌, 외부의 동적인 상태(예: 전역 설정값, 현재 세션 정보 등)를 스키마 내부 로직에서 조건부로 활용하고 싶을 때 사용함.

mode/reValidateMode 비교

mode 역할

onChange | onBlur | onSubmit | onTouched | all (기본값 : onSubmit)

mode의 경우 폼 제출 전 사용자의 액션에 따라 유효성 검사 타이밍을 결정한다.
기본값은 onSubmit으로, 불필요한 리렌더링이 가장 적어 성능상 가장 유리하다.

reValidateMode의 역할

onChange | onBlur | onSubmit (기본값: 'onChange')

사용자가 form을 submit한 후 오류가 있는 입력이 재검증될 때(onSubmit, handleSubmit 실행 시) 검증 전략 결정.
기본값은 onChange로 입력값이 변경될 때 마다 재검증 트리된다.
React Native의 경우 Custom register나 Controller 사용을 사용해야한다.

각 옵션에 따른 결과

onSubmit

첫 onSubmit이벤트에서 트리거됨.
onSubmit 이후에는 각 필드에 onChange 이벤트 리스너가 활성화되어, 사용자가 값을 수정할 때마다 즉각적으로 재검증을 수행.

onBlur

사용자가 입력을 마치고 포커스를 옮길 때 검증하므로, onChange보다 성능 효율적이면서 적절한 피드백을 제공.

onChange

필드의 값이 변경될 때마다 이벤트 트리거.
모든 키 입력마다 유효성 검사 로직이 실행되고 상태가 업데이트되어 리렌더링이 발생함.
따라서 성능에 영향 많이 받게되므로 사용에 주의 필요

onTouched

첫 blur 이벤트에서 트리거. 이후 모든 onChange이벤트 발생할 때마다 트리거

• UI 라이브러리(MUI, AntD 등)의 커스텀 컴포넌트는 표준 HTML input과 이벤트 전달 방식이 다를 수 있어 Controller를 사용하게 되는데, Controller의 render 프롭에서 제공하는 field.onBlur를 수동으로 연결해 주어야 RHF가 해당 필드가 'Touched' 되었음을 정확히 인지할 수 있음.

all

가장 엄격한 검증 방식으로 onBlur, onChange이벤트 발생 시 모두 트리거. 실시간 피드백을 극대화함

옵션에 따른 성능차이 : 왜 onChange를 주의해야 할까?

구독 기반 리렌더링 :

React Hook Form(RHF)은 기본적으로 비제어 방식(Uncontrolled)으로 불필요한 리렌더링을 방지하지만, mode: 'onChange'를 설정하면 키 입력마다 다음 사이클이 작동.

검증 함수 실행 -> 에러 객체 생성 -> 상태 업데이트

이때 RHF 내부의 상태가 업데이트될 때마다, 이 상태를 구독하고 있는 컴포넌트가 리액트의 리렌더링 사이클이 트리거되기 때문에 성능 부하가 발생한다.
입력값 자체는 비제어(Uncontrolled)지만 '검증 결과'는 반응형(Controlled)으로 관리되기 때문. 특히 복잡한 유효성 검사 로직이 포함되어 있거나 폼의 규모가 큰 경우, 메인 스레드를 점유하게 되어 사용자가 입력을 할 때 반응이 느려지는 타이핑 지연(Input Lag) 현상이 발생할 수 있다.

가비지 컬렉션(GC) 부하:

매 입력마다 새로운 errors 객체가 생성되고 참조가 변경되므로, 짧은 시간 내에 수많은 객체가 생성되고 파괴되는 과정은 브라우저의 가비지 컬렉터(GC)에 과부하를 주게 되며, 이는 특히 저사양 기기나 모바일 환경에서 성능 저하 및 버벅임의 직접적인 원인이 됨.

추천 이용 방식:

성능을 위해서는 기본값인 onSubmit이나 onBlur를 사용하는 것이 권장된다.
실시간 피드백이 반드시 필요하다면 처음부터 mode: 'onChange'를 쓰기보다 reValidateMode: 'onChange' 를 활용하여, 제출했을 때 에러 발생시에만 실시간으로 수정 여부를 검증하는 것도 효율적이다.