프로젝트를 시작하기 전부터 다음 프로젝트에서는 꼭 사용해보고 싶었던 스택 중 하나가 React Hook Form이었다. 이전 프로젝트에서는 웹 표준 등을 전혀 생각하지 않고 구현 하나만을 목표로 두었는데 그 중에서 제일 구현만 생각했다라고 느껴질 법한 부분이 form과 관련된 부분이었다. form 태그를 사용하지 않고 input/button 만을 사용해서 form처럼 동작하게 했는데, 이후 form 태그에 대해서 공부를 해보니 잘못 구현했다라는 생각이 들었다. 그리고 form에 input들이 많아지면서 useState 변수들을 정말 많이 선언하게 되고 관리도 불편하다는 생각이 들었다. 그러던 중 알게 된 게 React Hook Form 라이브러리로 form 관리에 좋다는 것이었다. 거기다가 React Hook Form을 많이들 사용해 배워두면 유용하겠다 싶었다.

※ 정리를 위해 프로젝트에서 구현한 코드들은 하단에서 정리하고 React Hook Form 사용법을 위한 간단한 코드들은 설명을 위한 최소한의 코드로 설명한다.

React Hook Form

아래 명령어를 입력해 라이브러리를 설치해준다.

npm install react-hook-form

다음과 같이 useForm 훅을 통해 필요한 함수들을 불러와 사용해주면 된다. 아래는 간단한 예시이다. 주요 함수들에 대해서는 아래에서 자세하게 설명한다.

const { register, handleSubmit, formState: { errors } } = useForm();

register

폼 필드를 react hook form의 관리 하에 등록한다. 즉, 각 폼 필드에 register를 사용하여 폼 데이터를 추적하고, 유효성 검사를 수행할 수 있다.

<input {...register("name", { required: true })} />

첫 번째 인자("name"): 필드 이름 지정
두 번째 인자({ required: true, maxLength: 10 }): 유효성 검사 규칙

required: 필수 입력 여부
min/max: 숫자형 입력에 대한 최소/최대값 설정
minLength/maxLength: 문자열의 최소/최대 길이 설정
pattern: 정규식을 이용한 입력 패턴 설정
validate: 커스텀 검증 함수를 추가하여 동적인 검증을 수행

<input 
	type="password" 
    {...register("confirmPassword", { 
    	required: "Please confirm your password", 
    	validate: (value, { password }) => 
    		value === password || "Passwords do not match"
    })} 
    placeholder="Confirm Password" 
/>

다음과 같을 때 confirmPassword는 필수 입력 값이고 pass와 동일해야 한다는 유효성 조건이 설정된 것이다.

handleSubmit

폼이 제출되었을 때 유효성 검사를 실행하고, 유효하면 제출 함수(콜백 함수)를 호출한다.

<form onSubmit={handleSubmit(onSubmit)}>
  {/* 폼 내용 */}
</form>

첫 번째 인자 말고도 두 번째 인자를 가지는데 이는 유효성 검사를 통과하지 못했을 때 실행될 콜백 함수이다.

handleSubmit(onSubmit, onError);

formState

폼의 전체 상태를 추적한다. 특히 유효성 검사 에러를 관리하는 데 자주 사용된다.

const { formState: { errors } } = useForm();

<input {...register("name", { required: true })} />
{errors.name && <p>This field is required</p>}

다음과 같은 경우, errors.name 값이 존재할 때(name의 유효성 검사에 오류가 있을 때) 오류 문구를 렌더링해주게 된다.

errors: 필드별 유효성 검사 오류를 포함하는 객체

formState.errors; // { name: { type: "required", message: "Name is required" } }

isDirty: 하나 이상의 필드 값이 변경되었는지 여부
isLoading: 폼 데이터나 옵션을 비동기로 로드 중인지 여부
isSubmitting: 폼이 제출 중인지 여부 (비동기 처리를 할 때 폼이 제출 상태임을 표시하는 데 사용)
isSubmitted: 폼이 한 번이라도 제출되었는지 여부
isSubmitSuccessful: 폼이 성공적으로 제출되었는지 여부
submitCount: 폼이 몇 번 제출되었는지를 카운트
isValid: 모든 필드가 유효한지 여부
dirtyFields: 사용자가 수정한 필드들을 추적 (변경된 필드들을 객체 형태로 제공)

formState.dirtyFields; // { name: true, email: true }

touchedFields: 사용자가 클릭 또는 포커스를 한 번이라도 준 필드를 추적

formState.touchedFields; // { name: true, email: true }

defaultValues: useForm에서 설정한 폼의 초기값

formState.defaultValues; // { name: "", email: "" }

reset

폼의 상태를 초기화한다.

reset();  // 폼을 초기 상태로 리셋
reset({ name: "John" });  // 특정 필드에 초기값을 주고 리셋

setValue

특정 필드의 값을 수동으로 설정한다.

setValue("name", "John Doe");

다음과 같이 세 번째 인자에 옵션 값을 넣어줄 수 있다. shouldValidate는 값을 설정할 때 해당 필드에 대해 유효성 검사를 즉시 실행한다. shouldDirty는 값을 설정할 때 해당 필드의 isDirty 상태가 true로 설정된다. 폼이 변경되었음을 사용자가 인식시키기 위해 주로 사용된다. shouldTouch값을 설정할 때 해당 필드의 isTouched 상태가 true로 설정된다. 사용자가 폼 필드를 상호작용했음을 표시할 때 주로 사용된다.

setValue("email", "test@example.com", { shouldValidate: true });
setValue("name", "John Doe", { shouldDirty: true });
setValue("age", 25, { shouldTouch: true });

getValues

폼의 현재 값을 가져온다.

const values = getValues();  // 폼의 모든 필드 값 가져오기
const nameValue = getValues("name");  // 특정 필드 값 가져오기

watch

특정 필드나 전체 폼 값의 변경을 실시간으로 감시한다.

const name = watch("name");  // "name" 필드의 값을 실시간으로 감시
const allValues = watch();  // 모든 필드 값 감시

trigger

수동으로 유효성 검사를 트리거한다. 특정 필드나 전체 필드를 검증할 수 있다. 특정 이벤트 발생 시 유효성 검사를 수동으로 실행할 때 사용된다.

trigger();  // 전체 필드에 대해 유효성 검사
trigger("name");  // 특정 필드에 대해 유효성 검사

useForm 옵션

useForm에 옵션을 전달해 폼의 유효성 검사와 폼 동작 방식을 제어할 수 있다.

useForm({
  mode: 'onSubmit',   
  criteriaMode: 'all',   
  reValidateMode: 'onChange', 
  shouldFocusError: true   
});

defaultValues

폼의 각 필드에 대한 초기값을 설정한다. 비동기 함수로도 설정 가능하다.

const { register } = useForm({
  defaultValues: {
    name: "John Doe",
    email: "john@example.com",
  }
});

const { register, handleSubmit } = useForm({
    defaultValues: async () => {
      // 비동기 작업으로 데이터를 가져옴 (Promise)
      const response = await fetch('https://api.example.com/user/1');
      const data = await response.json();

      // 비동기 작업 후에 데이터를 반환하여 defaultValues로 설정
      return {
        name: data.name,
        email: data.email,
        age: data.age,
      };
    }
});

resolver

외부 유효성 검사 라이브러리를 사용할 때 유효성 검사를 처리한다.

const schema = yup.object().shape({
  name: yup.string().required(),
  age: yup.number().positive().integer().required(),
});

const { register, handleSubmit, formState: { errors } } = useForm({
  resolver: yupResolver(schema)
});

context

폼의 유효성 검사와 상태 관리를 위한 전역 데이터를 공유할 때 사용된다. 주로 resolver와 함께 사용된다.

const { register } = useForm({
  context: { isLoggedIn: true }
});

delayError

유효성 검사 실패 시 에러 메시지를 표시하기 전까지 지연 시간을 설정한다. 필드 값이 변동되는 중간에는 에러 메시지가 바로 표시되지 않도록 할 수 있다.

useForm({
  delayError: 500 // 에러 메시지를 500ms 후에 표시
});

shouldUseNativeValidation

HTML5의 기본 유효성 검사 기능을 사용할지 여부

useForm({
  shouldUseNativeValidation: true
});

criteriaMode

필드 유효성 검사에서 발생한 에러를 처리할 때 첫 번째 에러만 반환할지, 모든 에러를 반환할지 결정한다. ('firstError' (default) | 'all')

mode

유효성 검사가 언제 실행될지를 설정한다. ('onSubmit' (default) | 'onBlur' | 'onChange' | 'onTouched' | 'all')

onSubmit: 폼 제출 시에만 유효성 검사를 수행
-> 사용자 입력이 바뀔 때마다 유효성 검사를 수행하지 않으므로 성능상 유리
onBlur: 폼 필드에서 포커스를 잃을 때마다 유효성 검사를 수행 (사용자가 입력 필드를 클릭한 후 다른 필드로 이동할 때마다 유효성 검사가 실행)
-> 필드의 오류를 즉시 사용자에게 알릴 수 있음
onChange: 폼 필드의 값이 변경될 때마다 유효성 검사를 수행
-> 많은 입력 변화가 발생할 때 성능에 영향을 미칠 수 있습니다.
onTouched: 폼 필드가 사용자가 상호작용한 후에만 유효성 검사를 수행
-> 사용자 경험을 고려하여, 입력이 완료된 후 유효성 검사를 하여 피드백을 제공
all: 모든 상태에서 유효성 검사를 수행

reValidateMode

유효성 검사가 실패한 후 언제 다시 유효성 검사를 실행할지 결정한다. ('onChange' (default) | 'onBlur')

shouldFocusError

유효성 검사가 실패한 필드로 자동 포커스를 이동할지 여부

shouldUnregister

폼에서 필드가 언마운트될 때 해당 필드의 값을 폼 상태에서 제거할지 여부

keepDirtyOnReinitialize

폼 데이터가 초기화될 때 필드의 dirty 상태를 유지할지를 결정한다.

useForm({
  defaultValues: { name: "John" },
  keepDirtyOnReinitialize: true
});

keepValues

폼 필드가 언마운트된 후에도 값을 유지할지 여부

프로젝트

대부분의 코드가 비슷하기 때문에 '닉네임 input'으로 정리한다.

const rNickname = /^[a-zA-Z0-9가-힣]{2,8}$/;

<input
	type="text"
	className={`user__input mt-[4px] ${touchedFields.nickname && errors.nickname ? 'user__input__invalid'
    : touchedFields.nickname && !errors.nickname && nickname ? 'user__input__valid': ''}`}
	placeholder="닉네임"
	aria-required="true"
	{...register('nickname', {
		required: '닉네임을 입력해주세요',
		pattern: {
			value: rNickname,
			message: '올바른 닉네임 형식을 입력해주세요',
		},
	})}
/>

프로젝트에서 유효성 검사를 실시간으로 진행해주기로 했다. 이때 onBlur와 onTouched 중에 어떤 값으로 해야할지, 둘이 무슨 차이가 있는지 고민했는데 onBlur는 필드에서 다른 필드로 이동할 때 실행된다고 한다. 그래서 그런지 input이 한 개만 있는 경우에는 유효성 검사가 잘 진행되지 않았다. 그래서 onTouched 속성으로 유효성 검사를 진행했다.
유효성 오류가 있을 때 input의 border의 색상도 변경되도록 구현해주었는데, errors.nickname이 true일 때 border의 색상을 빨갛게 해주었더니 default border가 빨간색이 되었다. required 속성을 가지고 있기 때문에 아무것도 입력되지 않아서 값이 제대로 입력되기 전까지는 항상 빨간색을 표시했다. 이는 의도와는 다르기 때문에 조건에 touchedFields.nickname을 주어 해당 값이 한 번이라도 클릭/포커스되었을 때라는 조건을 추가해주었다.
추가로 required 값이기 때문에 이를 웹 접근성을 위해서 aria-required를 true로 설정해주었다.

<p
	className={`text-sm min-h-[20px] font-medium ${nickname && !errors.nickname ? 'text-blue--500' : 'text-red--500'}`}
	role="alert"
	aria-hidden={errors.nickname ? 'true' : 'false'}
>
	{touchedFields.nickname && errors.nickname
	? errors.nickname.message
	: touchedFields.nickname && !errors.nickname && nickname
	? '사용가능한 닉네임 입니다'
	: ''}
</p>

오류가 있을 때 오류 문구도 추가해주어야 한다. 오류 문구도 비슷한 조건을 가진다. 이때 아무것도 입력되지 않았을 경우 문구를 표시하지 않기 위해 watch를 이용해 nickname 값이 존재하는지도 체크해주었다. p에 문구가 존재하지 않을 경우를 위해 aria-hidden 속성도 넣어주었다. (지금보니 조건이 이상한 것 같다. 수정이 필요할 것 같다.)

사용 후기

onChange 등 많은 것들이 생략되는 것 같고, 폼 데이터 처리도 간단해서 매우 만족스럽다. 다만, 원하는 모든 것을 다 구현할 수 있는지는 잘 모르겠다. 할 수 있는데 익숙하지 않고 잘 모르는 걸 수도 있겠지만 일단 border 처리라던지 실시간 오류 표시를 사이트에서 정말 많이하는 것 같은데 구현하기가 생각보다 어려웠다. 그래도 구현 난이도도 어렵지 않고, 관리도 편하기 때문에 다음에도 사용할 법한 느낌? 일단 만족!

참고 자료

React Hook Form 라이브러리 사용법