본문으로 건너뛰기

안동민 개발노트

본문 시작

폼 상태 커스텀 훅과 라이브러리

폼 상태와 검증을 커스텀 훅으로 추상화하고 폼 라이브러리가 필요한 기준을 판단합니다.

커스텀 훅을 이용한 폼 상태 추상화

현재 useForm 예제에서 values로 오류를 계산하고 제출 성공과 실패를 처리하는 흐름, 그리고 touched, 중복 제출, 서버 필드 오류처럼 별도 계약이 필요한 확장 축

React · Custom hook submit contract

현재 useForm 예제의 기준선은 valueserrorssubmit result 흐름입니다. 방문 여부, 동시 제출 방지, 서버 필드 오류는 자동으로 생기지 않으므로 별도 상태와 정책으로 추가합니다.

Current hook

입력 변경에서 제출 종료까지

  1. handleChange가 한 필드의 values를 갱신

    name을 key로 사용하고 checkbox만 checked boolean을 읽습니다.

  2. 제출 시 현재 values로 새 validationErrors를 계산

    isSubmitting을 켠 뒤 계산 결과를 errors에 저장합니다.

  3. 오류가 있으면 callback을 실행하지 않음

    오류가 없을 때만 호출자가 제공한 비동기 제출 callback을 await합니다.

  4. 예외는 일반 제출 오류로 기록하고 finally에서 종료

    성공한 callback은 필요할 때 resetForm을 호출하고, 모든 경로에서 제출 상태를 복구합니다.

폼 상태 축별 현재 예제와 확장 경계
상태 축현재 예제복잡도가 커질 때 추가할 계약
values입력 이벤트가 만드는 현재 값의 원천동적 필드의 기본값·등록 해제·배열 key 정책
errorsvalidate(values)가 만든 클라이언트 오류와 일반 submit 오류스키마 오류와 서버 오류를 필드·폼 수준으로 명시적으로 매핑
touched · dirty현재 훅은 추적하지 않음blur 전이와 오류 노출 시점을 별도 상태로 관리
isSubmitting버튼 비활성화와 진행 문구를 위한 화면 상태동시 요청 guard와 idempotency는 별도 설계
Values

현재 값의 원천

입력 변경은 해당 필드 값을 갱신하고 검증은 이 snapshot을 읽습니다.

Errors

계산 결과와 제출 오류

클라이언트 검증 오류와 일반 제출 오류를 현재 예제가 저장합니다.

Touched · dirty

현재 예제 밖의 축

오류 노출 시점이 필요할 때 blur와 변경 이력을 별도로 추가합니다.

Submitting

진행 표시와 복구

finally로 상태를 복구하되 동시 요청 차단은 별도 guard가 필요합니다.

Server errors

명시적인 매핑

서버 업무 규칙 실패를 필드 또는 폼 오류로 옮기는 정책을 따로 둡니다.

화면의 disabled는 사용자 피드백일 뿐 요청 중복 방지를 보장하지 않습니다. 제출 guard와 서버 idempotency가 필요하면 훅 계약에 명시합니다.

useReducer를 사용하더라도, 매 폼마다 리듀서와 handleChange 로직을 작성하는 것은 여전히 반복적인 작업일 수 있습니다.

이때 커스텀 훅(Custom Hook)을 사용하면 이러한 폼 상태 관리 로직을 추상화하여 재사용성을 극대화할 수 있습니다.

useForm과 같은 커스텀 훅은 다음과 같은 기능을 제공할 수 있습니다.

  • 폼 데이터 상태 관리 (useState 또는 useReducer 기반)
  • 모든 input 필드에 적용할 수 있는 범용 handleChange 함수
  • 폼 제출(handleSubmit) 시 데이터를 처리하는 로직
  • 유효성 검사 로직 및 에러 상태 관리
useForm 커스텀 훅 예시
src/hooks/useForm.js
import { useState, useCallback } from 'react';

/**
 * 폼 상태와 유효성 검사를 관리하는 커스텀 훅
 * @param {object} initialValues - 폼 필드의 초기 값
 * @param {function} validate - 폼 데이터 객체를 받아 에러 객체를 반환하는 유효성 검사 함수
 * @returns {{ values, errors, handleChange, handleSubmit, resetForm }}
 */
const useForm = (initialValues, validate) => {
  const [values, setValues] = useState(initialValues);
  const [errors, setErrors] = useState({});
  const [isSubmitting, setIsSubmitting] = useState(false); // 제출 중 상태 (선택 사항)

  const handleChange = useCallback((e) => {
    const { name, value, type, checked } = e.currentTarget;
    setValues(prevValues => ({
      ...prevValues,
      [name]: type === 'checkbox' ? checked : value,
    }));
    // 입력 시 실시간 유효성 검사를 하고 싶다면 여기에 validate 로직을 추가할 수 있습니다.
    // 하지만 보통은 제출 시점에 모든 유효성을 검사하는 것이 일반적입니다.
  }, []);

  const handleSubmit = useCallback((callback) => async (e) => {
    e.preventDefault();
    setIsSubmitting(true);

    try {
      const validationErrors = validate(values); // 유효성 검사 실행
      setErrors(validationErrors);

      if (Object.keys(validationErrors).length === 0) {
        // 에러가 없으면 콜백 함수 실행
        await callback(values); // 비동기 콜백을 지원하기 위해 await
      }
    } catch (submitError) {
      // 검증 또는 제출 콜백에서 발생한 오류 처리 (예: API 제출 실패)
      console.error("폼 제출 오류:", submitError);
      setErrors(prevErrors => ({
        ...prevErrors,
        submit: submitError.message || '폼 제출 중 오류가 발생했습니다.'
      }));
    } finally {
      setIsSubmitting(false);
    }
  }, [values, validate]);

  const resetForm = useCallback(() => {
    setValues(initialValues);
    setErrors({});
    setIsSubmitting(false);
  }, [initialValues]);

  return {
    values,
    errors,
    isSubmitting,
    handleChange,
    handleSubmit,
    resetForm,
  };
};

export default useForm;
useForm 커스텀 훅 사용 예시
src/components/UserRegistrationForm.js
import React from 'react';
import useForm from '../hooks/useForm'; // 커스텀 훅 임포트

// 유효성 검사 함수 (useForm에 전달될 콜백)
const validateUserInfo = (values) => {
  const errors = {};
  if (!values.username.trim()) {
    errors.username = '사용자 이름은 필수입니다.';
  } else if (values.username.length < 3) {
    errors.username = '사용자 이름은 3자 이상이어야 합니다.';
  }
  if (!values.email.trim()) {
    errors.email = '이메일은 필수입니다.';
  } else if (!/\S+@\S+\.\S+/.test(values.email)) {
    errors.email = '유효한 이메일 주소를 입력해주세요.';
  }
  if (!values.password) {
    errors.password = '비밀번호는 필수입니다.';
  } else if (values.password.length < 6) {
    errors.password = '비밀번호는 6자 이상이어야 합니다.';
  }
  if (values.password !== values.confirmPassword) {
    errors.confirmPassword = '비밀번호가 일치하지 않습니다.';
  }
  return errors;
};

function UserRegistrationForm() {
  const {
    values,
    errors,
    isSubmitting,
    handleChange,
    handleSubmit,
    resetForm,
  } = useForm(
    { username: '', email: '', password: '', confirmPassword: '' }, // 초기값
    validateUserInfo // 유효성 검사 함수
  );

  // 폼 제출 로직 (useForm의 handleSubmit에 전달될 콜백)
  const onSubmit = async (formData) => {
    // 실제 API 호출 로직을 여기에 작성
    console.log('폼 데이터 제출 시작:', formData);
    try {
      // 가상 API 호출 지연
      await new Promise(resolve => setTimeout(resolve, 1000));
      console.log('폼 데이터 제출 완료:', formData);
      alert('회원가입이 완료되었습니다!');
      resetForm(); // 제출 성공 후 폼 초기화
    } catch (error) {
      console.error('회원가입 실패:', error);
      alert('회원가입에 실패했습니다.');
      throw error; // useForm 훅에서 에러를 잡을 수 있도록 다시 던짐
    }
  };

  return (
    <div style={{ maxWidth: '600px', margin: '30px auto', padding: '25px', border: '1px solid #ddd', borderRadius: '8px', boxShadow: '0 2px 10px rgba(0,0,0,0.05)', backgroundColor: '#fff' }}>
      <h2 style={{ textAlign: 'center', color: '#2c3e50', marginBottom: '30px' }}>회원가입 폼 (커스텀 훅)</h2>
      <form onSubmit={handleSubmit(onSubmit)} aria-busy={isSubmitting}> {/* handleSubmit에 실제 제출 함수를 전달 */}
        <div style={{ marginBottom: '15px' }}>
          <label htmlFor="registration-username" style={{ display: 'block', marginBottom: '5px' }}>사용자 이름:</label>
          <input
            id="registration-username"
            type="text"
            name="username"
            value={values.username}
            onChange={handleChange}
            aria-invalid={Boolean(errors.username)}
            aria-describedby={errors.username ? 'registration-username-error' : undefined}
            style={{ width: '100%', padding: '8px', border: errors.username ? '1px solid red' : '1px solid #ccc' }}
          />
          {errors.username && <p id="registration-username-error" style={{ color: 'red', fontSize: '0.8em', marginTop: '5px' }}>{errors.username}</p>}
        </div>
        <div style={{ marginBottom: '15px' }}>
          <label htmlFor="registration-email" style={{ display: 'block', marginBottom: '5px' }}>이메일:</label>
          <input
            id="registration-email"
            type="email"
            name="email"
            value={values.email}
            onChange={handleChange}
            aria-invalid={Boolean(errors.email)}
            aria-describedby={errors.email ? 'registration-email-error' : undefined}
            style={{ width: '100%', padding: '8px', border: errors.email ? '1px solid red' : '1px solid #ccc' }}
          />
          {errors.email && <p id="registration-email-error" style={{ color: 'red', fontSize: '0.8em', marginTop: '5px' }}>{errors.email}</p>}
        </div>
        <div style={{ marginBottom: '15px' }}>
          <label htmlFor="registration-password" style={{ display: 'block', marginBottom: '5px' }}>비밀번호:</label>
          <input
            id="registration-password"
            type="password"
            name="password"
            value={values.password}
            onChange={handleChange}
            aria-invalid={Boolean(errors.password)}
            aria-describedby={errors.password ? 'registration-password-error' : undefined}
            style={{ width: '100%', padding: '8px', border: errors.password ? '1px solid red' : '1px solid #ccc' }}
          />
          {errors.password && <p id="registration-password-error" style={{ color: 'red', fontSize: '0.8em', marginTop: '5px' }}>{errors.password}</p>}
        </div>
        <div style={{ marginBottom: '15px' }}>
          <label htmlFor="registration-confirm-password" style={{ display: 'block', marginBottom: '5px' }}>비밀번호 확인:</label>
          <input
            id="registration-confirm-password"
            type="password"
            name="confirmPassword"
            value={values.confirmPassword}
            onChange={handleChange}
            aria-invalid={Boolean(errors.confirmPassword)}
            aria-describedby={errors.confirmPassword ? 'registration-confirm-password-error' : undefined}
            style={{ width: '100%', padding: '8px', border: errors.confirmPassword ? '1px solid red' : '1px solid #ccc' }}
          />
          {errors.confirmPassword && <p id="registration-confirm-password-error" style={{ color: 'red', fontSize: '0.8em', marginTop: '5px' }}>{errors.confirmPassword}</p>}
        </div>
        {errors.submit && <p role="alert" style={{ color: 'red', fontSize: '0.9em', marginTop: '10px' }}>{errors.submit}</p>} {/* 제출 오류 */}
        <button type="submit" className="button" disabled={isSubmitting} style={{ width: '100%', padding: '10px' }}>
          {isSubmitting ? '등록 중...' : '회원가입'}
        </button>
      </form>
    </div>
  );
}

export default UserRegistrationForm;

useForm 커스텀 훅은 폼 컴포넌트의 로직을 훨씬 간결하고 재사용 가능하게 만듭니다.

이제 각 폼 컴포넌트는 오직 자신의 폼 필드와 유효성 검사 규칙만 정의하면 됩니다.


폼 라이브러리 활용

실제 프로덕션 환경에서 매우 복잡하고 큰 폼을 다룰 때는 useReducer나 직접 만든 useForm 커스텀 훅만으로도 한계에 부딪힐 수 있습니다.

특히 다음과 같은 상황에서는 “상태를 직접 들고 있을 수 있는가”보다 “필드 등록, 검증, 오류 노출, 제출 복구를 일관된 계약으로 유지할 수 있는가”를 봐야 합니다.

  • 필드 수가 늘어 값, 오류, 방문 여부, dirty 상태를 따로 추적해야 한다.
  • 조건부 렌더링 때문에 필드를 숨길 때 값을 유지할지 해제할지 결정해야 한다.
  • 동적으로 추가/제거되는 필드 배열에서 key, 기본값, item-level error, array-level error를 분리해야 한다.
  • 클라이언트 스키마 검증과 서버 중복 확인 같은 비동기 검증이 함께 필요하다.
  • 입력 하나가 큰 폼 전체를 다시 렌더링해 타이핑 지연이 보인다.

이러한 복잡성을 해결하기 위해 React Hook Form이나 Formik과 같은 전문적인 폼 관리 라이브러리들이 존재합니다.

이 라이브러리들은 폼 상태 관리, 유효성 검사, 제출 처리, 그리고 성능 최적화를 위한 다양한 기능을 제공합니다.

아래 다이어그램은 직접 구현한 훅에서 전문 폼 라이브러리로 넘어가야 하는 신호와 선택 기준을 정리한 것입니다.

직접 만든 useForm, React Hook Form, Formik의 필드 연결, 검증, 동적 배열, 렌더 범위를 비교하고 화면, 폼 로직, 스키마, 서버의 소유권 경계를 구분하는 선택표

React · Form tool boundary

폼 도구는 필드 개수보다 값·오류·방문·동적 배열·비동기 검증·렌더 범위가 함께 움직이는지로 고릅니다. 어떤 도구를 써도 클라이언트 스키마와 서버의 최종 판단 경계는 사라지지 않습니다.

직접 훅, React Hook Form, Formik 선택 기준
기준직접 useFormReact Hook FormFormik
필드 연결name, value, onChange 계약을 직접 작성registerdefaultValues, 제어형 위젯은 ControllerinitialValues, values, Field 중심의 명시적 상태
검증 위치validate(values)와 오류 매핑을 직접 소유resolver로 Zod·Yup 같은 스키마 연결validate 또는 validationSchema
동적 배열key, 기본값, item·array 오류 정책을 직접 설계useFieldArray로 추가·삭제·재정렬FieldArray로 배열 전이를 표현
렌더 범위컴포넌트 분리와 memoization을 직접 판단필요한 필드·formState 구독 범위를 좁힘명시적 상태 흐름을 유지하며 FastField·분할을 검토
우선 선택필드와 검증·제출 계약이 작고 안정적일 때등록형 입력, 동적 구조, 세밀한 구독이 중요할 때React 상태가 드러나는 모델과 디버깅 흐름을 선호할 때
Direct hook

작고 안정적인 계약

값, 검증, 제출과 오류 매핑을 애플리케이션이 직접 소유합니다.

React Hook Form

등록·동적 구조·구독

register, Controller, useFieldArray, resolver를 조합합니다.

Formik

명시적인 React 상태

values, errors, touched 흐름과 컴포넌트 API를 사용합니다.

Ownership invariant

도구가 바뀌어도 책임 경계는 유지한다

  1. 화면 컴포넌트

    열림, 접힘, 포커스처럼 표시 상태와 필드 UI를 소유합니다.

  2. 폼 로직 또는 라이브러리

    values, errors, touched, dirty, 제출 전이를 일관된 모델로 관리합니다.

  3. 클라이언트 스키마와 서버

    스키마는 즉시 피드백 규칙을 공유하고, 권한·중복·최종 유효성은 서버가 판단합니다.

라이브러리는 값의 새 소유자가 아니라 필드 등록과 상태 전이를 조직합니다. 서버 오류를 필드나 폼 수준에 연결하는 방식은 앱이 정합니다.

  • React Hook Form
    • 필드 등록 중심: registerdefaultValues로 네이티브 입력을 연결하고, 필요한 필드 상태만 구독해 리렌더링 범위를 줄입니다.
    • 제어형 컴포넌트 연결: UI 라이브러리의 날짜 선택기, 자동완성처럼 제어형 흐름이 필요한 입력은 Controller로 감쌉니다. 이 경우에는 해당 컴포넌트의 렌더 비용도 함께 봐야 합니다.
    • 동적 배열과 스키마 검증: useFieldArray로 append/remove/reorder를 관리하고, resolver로 Yup, Zod 같은 스키마 유효성 검사 라이브러리와 통합합니다.
    • 폼 상태 분리: formStateerrors, dirtyFields, isSubmitting 같은 값을 필요한 위치에서만 읽도록 설계합니다.
  • Formik
    • 명시적인 상태 모델: initialValues, values, errors, touched가 React 상태 흐름 안에 드러나므로 폼 상태를 읽고 디버깅하기 쉽습니다.
    • 검증 계약: validate 또는 validationSchema로 검증 위치를 고정하고, 제출 오류와 필드 오류를 나눠 관리할 수 있습니다.
    • 컴포넌트 API: Field, FieldArray, FastField를 활용할 수 있지만, 큰 폼에서는 갱신 범위를 의식해 컴포넌트를 나누어야 합니다.

이러한 라이브러리는 다음 절인 폼 유효성 검사에서 더 자세히 다룹니다.

이 절에서는 직접 훅, React Hook Form, Formik 중 무엇을 고를지 판단하기 위해 필드 등록 방식, 검증 위치, 동적 배열, 리렌더링 범위를 먼저 비교합니다.


9장 2절 복잡한 폼 상태 관리하기는 여기까지입니다.

이 장에서는 여러 입력 필드를 하나의 상태 객체로 관리하는 기본 패턴부터 시작하여, useReducer를 사용하여 상태 로직을 중앙 집중화하는 방법, 그리고 폼 관련 로직을 재사용 가능한 커스텀 훅으로 추상화하는 고급 패턴까지 살펴보았습니다.

마지막으로, 매우 복잡한 폼을 다룰 때 유용한 전문 폼 관리 라이브러리의 존재와 필요성에 대해서도 간략히 언급했습니다.