useForm으로 국가별 배송지 폼 만들기

Dev
2025-05-20

React Hook Form과 useForm, useController를 활용해 국가별 입력 정책을 반영한 배송지 등록/수정/삭제 폼을 구현한 포스트입니다.

배송지 등록/수정 모달은 디자인이 유사해 하나의 컴포넌트로 통합하고, mode를 create | edit으로 받아 분기 처리했다. mode 캡쳐본

그리고 각 국가별 입력 요구사항(CPF, 신분증번호 등)은 조건부 렌더링과 정규식을 적용해 유효성 검사를 구성했다. 폼은 control, setValue를 props로 받아 react-hook-form과 연결되며, handleNamePattern을 통해 국가 코드에 따라 이름 필드 제한도 설정했다.

한국, 일본, 중국 배송지 등록하는 화면을 동영상으로 첨부했다!

공통 UI는 재사용하고, 국가별 정책은 별도 컴포넌트로 분리해 가독성과 유지보수성을 확보하였으며, 유효성 검사 로직도 국가별로 분기 처리하여 사용자 경험을 개선했다.

📦 국가별 주요 처리 내용

  • 🇰🇷 한국: Daum 주소검색 API 연동 (모바일: 팝업 / PC: 임베드)
  • 🇨🇳 중국: 신분증 번호 입력 필드 및 우편번호 검색 (china-division 패키지 사용)
  • 🇯🇵 일본: 우편번호 검색 API 연동
  • 🇧🇷 브라질: CPF 입력란 재검토 요청 후 제거
  • 🇹🇭🇹🇼 태국·대만: 국가별 주의사항 조건부 적용
  • 그 외 국가: 유효성 검사 조건 정리 및 공통 파일로 분리

AddressInput의 register 속성 제거

const AddressInput = <TFormInput extends FieldValues = FieldValues>({
  name,
  type = 'text',
  placeholder,
  label,
  required,
  control,
  Icon,
  countryCode,
  maxLength,
  readOnly,
  pattern,
  errorMessage,
  onClearErrorMessage,
}: AddressInputProps<TFormInput>) => {
  const {
    field: { onChange, value, ref },
    fieldState: { error },
  } = useController({
    name,
    control,
    rules: {
      required,
      pattern,
      maxLength,
    },
  });

기존에는 register와 useController를 함께 사용했는데, 이는 같은 필드를 중복 등록하게 되어 충돌이 발생할 수 있다. 공식 문서에 따르면 useController는 내부적으로 해당 필드를 register하기 때문에 둘 중 하나만 사용해야 한다고 안내하고 있다.

또한 useController의 rules 옵션으로 유효성 검사도 처리할 수 있기 때문에, 굳이 register를 병행하지 않아도 된다. 이러한 이유로 AddressInput 컴포넌트에서 register 관련 코드를 제거하고, useController만으로 필드 등록과 유효성 검사를 관리하도록 수정했다!
해당 내용은 react-hook-form 공식문서에 나와있다.

더 구체적으로는 아래의 캡쳐본을 보자!

register 캡쳐본