회원가입 폼 만들기
손으로 만든 회원가입 폼을 React Hook Form과 Yup으로 옮겨, 검사 규칙과 검사 시점, 제출 상태, 서버 오류 표시가 각각 어떤 코드로 줄어드는지 확인합니다.
앞의 세 글에서 회원가입 폼 하나를 손으로 키워 왔습니다. 값을 담는 리듀서, 그것을 감싼 useForm 훅, 규칙을 적은 validateSignup, 칸을 벗어날 때의 검사, 제출 중 상태와 서버 오류까지 직접 만들었습니다. 동작은 하지만 요구가 하나 늘 때마다 훅을 고쳐야 했고, 두 비밀번호의 어긋남처럼 아직 풀지 않은 문제도 남아 있습니다. 이 실습에서는 같은 폼을 React Hook Form과 Yup으로 옮깁니다. 화면과 동작은 그대로 두고, 우리가 쓴 코드가 얼마나 사라지는지를 봅니다.
이 글을 읽고 나면 다음을 할 수 있습니다.
- 검사 규칙을 Yup 스키마로 적고 React Hook Form에 연결합니다.
register로 입력 칸을 등록해 값과 오류, 검사 시점을 라이브러리에 맡깁니다.- 서버가 거절한 이유를 해당 칸이나 폼 전체의 오류로 보여 주고, 성공했을 때만 폼을 비웁니다.
시작 상태와 설치
앞 글을 마친 프로젝트에서 시작합니다. src 아래에 다음 파일이 있어야 합니다.
이 실습에서 그대로 쓰는 파일은 App.jsx, Field.jsx, signup.js 셋입니다. 앞 글을 건너뛰었다면 아래 내용으로 세 파일을 만들면 됩니다. SignupForm.jsx는 새로 쓰고, useForm.js는 마지막에 지웁니다.
그대로 쓰는 세 파일
import SignupForm from './components/SignupForm';
export default function App() {
return (
<div>
<h1>회원가입</h1>
<SignupForm />
</div>
);
}export default function Field({ label, error, ...inputProps }) {
const id = inputProps.name;
const errorId = `${id}-error`;
return (
<div>
<label htmlFor={id}>{label}</label>
<input
id={id}
aria-invalid={Boolean(error)}
aria-describedby={error ? errorId : undefined}
{...inputProps}
/>
{error && <p id={errorId} role="alert">{error}</p>}
</div>
);
}export function requestSignup(values) {
return new Promise((resolve, reject) => {
setTimeout(() => {
if (values.email === '[email protected]') {
const error = new Error('이미 가입된 이메일입니다.');
error.field = 'email';
reject(error);
} else if (values.email === '[email protected]') {
reject(new Error('서버에 연결하지 못했습니다. 잠시 뒤 다시 시도하세요.'));
} else {
resolve({ username: values.username });
}
}, 1000);
});
}requestSignup은 서버 대신 쓰는 함수입니다. 1초 뒤에 응답하며, 이메일이 [email protected]이면 field가 'email'인 오류로, [email protected]이면 field가 없는 오류로 실패하고, 그 밖에는 성공합니다.
터미널에서 개발 서버를 잠시 멈추고 패키지 셋을 설치합니다.
npm install react-hook-form yup @hookform/resolversreact-hook-form은 폼의 값과 오류, 제출 상태를 맡는 라이브러리이고, yup은 검사 규칙을 적는 라이브러리입니다. 둘은 서로를 모르므로, @hookform/resolvers가 Yup의 검사 결과를 React Hook Form이 알아듣는 모양으로 바꿔 이어 줍니다. 이 글은 2026년 11월에 npm에 올라 있는 react-hook-form 7.92, yup 1.7, @hookform/resolvers 7.0을 기준으로 썼습니다. 설치가 끝나면 npm run dev로 개발 서버를 다시 켭니다.
1단계: 규칙을 스키마로 옮기고 입력 칸을 등록하기
먼저 서버 요청은 빼고, 검사와 오류 표시까지만 옮깁니다. SignupForm.jsx의 내용을 모두 지우고 다음 내용으로 바꿉니다.
import { useForm } from 'react-hook-form';
import { yupResolver } from '@hookform/resolvers/yup';
import * as yup from 'yup';
import Field from './Field';
const defaultValues = {
username: '',
email: '',
password: '',
confirmPassword: '',
};
const schema = yup.object({
username: yup
.string()
.trim()
.required('사용자 이름을 입력하세요.')
.min(3, '사용자 이름은 3자 이상이어야 합니다.'),
email: yup
.string()
.required('이메일을 입력하세요.')
.email('이메일 형식이 올바르지 않습니다.'),
password: yup
.string()
.required('비밀번호를 입력하세요.')
.min(8, '비밀번호는 8자 이상이어야 합니다.')
.matches(/[A-Z]/, '대문자를 하나 이상 넣어 주세요.')
.matches(/[a-z]/, '소문자를 하나 이상 넣어 주세요.')
.matches(/[0-9]/, '숫자를 하나 이상 넣어 주세요.'),
confirmPassword: yup
.string()
.required('비밀번호를 한 번 더 입력하세요.')
.oneOf([yup.ref('password')], '비밀번호가 일치하지 않습니다.'),
});
export default function SignupForm() {
const {
register,
handleSubmit,
formState: { errors },
} = useForm({
defaultValues,
resolver: yupResolver(schema),
});
function onSubmit(data) {
alert(`${data.username} 님, 가입을 신청했습니다.`);
}
return (
<form onSubmit={handleSubmit(onSubmit)} noValidate>
<Field
label="사용자 이름"
error={errors.username?.message}
{...register('username')}
/>
<Field
label="이메일"
type="email"
error={errors.email?.message}
{...register('email')}
/>
<Field
label="비밀번호"
type="password"
error={errors.password?.message}
{...register('password')}
/>
<Field
label="비밀번호 확인"
type="password"
error={errors.confirmPassword?.message}
{...register('confirmPassword')}
/>
<button type="submit">가입하기</button>
</form>
);
}맨 위의 useForm은 이제 우리가 만든 훅이 아니라 react-hook-form이 주는 훅입니다. 이름이 같은 것은 우연이 아닙니다. 앞에서 만든 훅과 맡은 일이 같습니다. 달라진 곳을 차례로 봅니다.
schema가 validatePassword와 validateSignup을 대신합니다. yup.object()에 필드 이름마다 규칙을 이어 붙여 적습니다. yup.string()은 문자열이라는 뜻이고, 그 뒤의 required, min, email, matches가 규칙이며, 각 규칙에 넘긴 문자열이 그 규칙을 어겼을 때의 메시지입니다. 앞 글에서 if와 else if로 적었던 규칙을 여기서는 메서드로 선언합니다. 다만 오류가 정해지는 순서가 메서드를 적은 순서와 항상 같지는 않습니다. trim()은 규칙이 아니라 값을 다듬는 단계로, 검사하기 전에 앞뒤 공백을 뺍니다. 비밀번호 확인의 oneOf([yup.ref('password')], ...)는 허용하는 값의 목록에 "같은 객체의 password 값"을 넣은 것이어서, 비밀번호와 같을 때만 통과합니다.
register('username')은 name, onChange, onBlur, ref 네 속성을 담은 객체를 돌려줍니다. 이것을 {...}로 Field에 펼쳐 넣으면 Field가 다시 <input>에 넘겨, 라이브러리가 그 입력 칸을 직접 붙잡습니다. 우리가 넘기던 value, onChange, onBlur 세 줄이 이 한 줄로 바뀌었습니다. value가 없다는 점을 눈여겨봅니다. React Hook Form은 입력값을 state에 두지 않고 첫 글에서 본 비제어 방식으로 DOM에 두었다가 필요할 때 ref로 읽습니다. Field를 고치지 않아도 되는 것은, React 19에서 함수 컴포넌트가 ref를 다른 props와 똑같이 받기 때문입니다. ref는 inputProps에 담겨 <input>까지 그대로 전달됩니다.
handleSubmit(onSubmit)은 우리 훅의 것과 생김새가 같습니다. 제출되면 지금 값을 resolver에 넘겨 검사하고, 통과했을 때만 onSubmit에 값을 넘겨 부릅니다. 걸렸다면 formState.errors에 필드 이름마다 message를 가진 객체가 들어갑니다. 그래서 Field에는 errors.username?.message를 넘깁니다. ?.은 errors.username이 없을 때 오류를 내지 않고 undefined를 돌려주는 연산자입니다.
저장한 뒤 아무것도 입력하지 않고 "가입하기"를 누릅니다.
체크포인트: 네 칸 아래에 "사용자 이름을 입력하세요.", "이메일을 입력하세요.", "비밀번호를 입력하세요.", "비밀번호를 한 번 더 입력하세요."가 보이고, 커서가 사용자 이름 칸으로 옮겨 갑니다. 검사에 걸리면 오류가 있는 첫 칸에 포커스를 주는 것은 라이브러리의 기본 동작입니다. 이어서 사용자 이름 칸에 mina를 입력하면 두 글자까지는 "사용자 이름은 3자 이상이어야 합니다."가 보이다가 세 번째 글자에서 사라집니다. 앞 글의 연습 문제 3에서 손으로 만든 동작입니다.
네 칸에 mina (앞뒤에 공백 두 칸), [email protected], Abcdef1!, Abcdef1!를 넣고 제출하면 "mina 님, 가입을 신청했습니다."가 뜹니다. 이름 앞의 공백이 알림창에 없는 것은, onSubmit이 받는 data가 스키마의 trim()을 거친 값이기 때문입니다.
React Hook Form과 Yup의 단일 폼 처리 파이프라인 — 상태 추적
동일 필드 이름의 현재 값이 handleSubmit/resolver를 지나 errors 또는 onSubmit data로 갈립니다. 입력/검증 결과/요청 허용과 서버 검증을 추적합니다.
React · React Hook Form · Yup resolver
한 필드 이름이 등록·초기값·스키마를 묶습니다
register가 수집한 현재 값은 handleSubmit에서 yupResolver(schema)로 전달됩니다. 같은 필드 이름을 defaultValues와 schema가 공유해야 오류가 올바른 입력에 연결되고, 검증 결과에 따라 errors 또는 onSubmit으로 갈립니다.
username · email · password · confirmPassword
필드를 이름으로 연결
register(name)가 현재 입력 값을 수집하며 같은 이름을 defaultValues와 schema에서 사용합니다.
handleSubmit이 제출 처리
브라우저 submit 이벤트를 받아 현재 폼 값을 resolver에 전달합니다.
yupResolver(schema)
공통 키의 값을 Yup 규칙으로 검사하고 성공 값 또는 필드 오류를 반환합니다.
errors로 복귀
필드별 메시지를 해당 입력의 접근성 설명과 연결하고 API 요청은 보내지 않습니다.
onSubmit(data) 실행
resolver가 통과시킨 데이터만 제출 함수에 전달됩니다. 서버는 같은 업무 규칙을 다시 검증합니다.
defaultValues, register, schema의 필드 이름이 어긋나면 초기값·오류·제출 데이터가 서로 다른 키를 가리킵니다. 같은 이름으로 유지하되 클라이언트 통과를 서버 승인으로 간주하지 않습니다.
이 예의 조건
- 도표의 전체 구조와 설명은 위 관계도와 표에서 볼 수 있습니다. 아래 표에도 도표의 관계·조건·라벨·설명·주석을 모았습니다.
- 두 칸의 위치는 고정입니다. 현재 상태는 그 순간의 값이고, 동작·이유는 그 조건에서의 판정과 변화 원인입니다. 독립 비교와 실패 분기는 별도 조건이므로 모든 분기를 한 요청의 실행 순서로 이어 읽지 않습니다.
관계도의 보충 설명
| 구분 | 내용 |
|---|---|
| 도표 설명 | register가 수집한 현재 값은 handleSubmit에서 yupResolver(schema)로 전달됩니다. 같은 필드 이름을 defaultValues와 schema가 공유해야 오류가 올바른 입력에 연결되고, 검증 결과에 따라 errors 또는 onSubmit으로 갈립니다. |
| 도표 설명 | register(name)가 현재 입력 값을 수집하며 같은 이름을 defaultValues와 schema에서 사용합니다. |
| 도표 설명 | handleSubmit이 제출 처리 |
| 도표 설명 | errors로 복귀 |
| 도표 설명 | defaultValues, register, schema의 필드 이름이 어긋나면 초기값·오류·제출 데이터가 서로 다른 키를 가리킵니다. 같은 이름으로 유지하되 클라이언트 통과를 서버 승인으로 간주하지 않습니다. |
| 장면 | 현재 관찰값 | 설명 | 변화 이유 |
|---|---|---|---|
| 동일 field 이름 | 연결: 같은 field 이름 / 입력: 현재 values | defaultValues·register·schema가 같은 username·email·password·confirmPassword를 연결합니다 | 필드 이름이 오류와 기본값을 잇습니다 |
| resolver 검사 | invalid: formState.errors / valid: onSubmitdata | handleSubmit이 yupResolver로 현재 값을 검사합니다 | 검증 실패는 API 요청으로 가지 않습니다 |
| 서버 검증 | client: valid data / server: 독립 검증 | 통과한 data로 API를 호출하되 서버의 판정을 기다립니다 | 권한·중복·무결성의 최종 판단은 서버가 합니다 |
React Hook Form과 Yup의 단일 폼 처리 파이프라인 — 상태 추적
동일 필드 이름의 현재 값이 handleSubmit/resolver를 지나 errors 또는 onSubmit data로 갈립니다. 입력/검증 결과/요청 허용과 서버 검증을 추적합니다.
React · React Hook Form · Yup resolver
한 필드 이름이 등록·초기값·스키마를 묶습니다
register가 수집한 현재 값은 handleSubmit에서 yupResolver(schema)로 전달됩니다. 같은 필드 이름을 defaultValues와 schema가 공유해야 오류가 올바른 입력에 연결되고, 검증 결과에 따라 errors 또는 onSubmit으로 갈립니다.
username · email · password · confirmPassword
필드를 이름으로 연결
register(name)가 현재 입력 값을 수집하며 같은 이름을 defaultValues와 schema에서 사용합니다.
handleSubmit이 제출 처리
브라우저 submit 이벤트를 받아 현재 폼 값을 resolver에 전달합니다.
yupResolver(schema)
공통 키의 값을 Yup 규칙으로 검사하고 성공 값 또는 필드 오류를 반환합니다.
errors로 복귀
필드별 메시지를 해당 입력의 접근성 설명과 연결하고 API 요청은 보내지 않습니다.
onSubmit(data) 실행
resolver가 통과시킨 데이터만 제출 함수에 전달됩니다. 서버는 같은 업무 규칙을 다시 검증합니다.
defaultValues, register, schema의 필드 이름이 어긋나면 초기값·오류·제출 데이터가 서로 다른 키를 가리킵니다. 같은 이름으로 유지하되 클라이언트 통과를 서버 승인으로 간주하지 않습니다.
이 예의 조건
- 도표의 전체 구조와 설명은 위 관계도와 표에서 볼 수 있습니다. 아래 표에도 도표의 관계·조건·라벨·설명·주석을 모았습니다.
- 두 칸의 위치는 고정입니다. 현재 상태는 그 순간의 값이고, 동작·이유는 그 조건에서의 판정과 변화 원인입니다. 독립 비교와 실패 분기는 별도 조건이므로 모든 분기를 한 요청의 실행 순서로 이어 읽지 않습니다.
관계도의 보충 설명
| 구분 | 내용 |
|---|---|
| 도표 설명 | register가 수집한 현재 값은 handleSubmit에서 yupResolver(schema)로 전달됩니다. 같은 필드 이름을 defaultValues와 schema가 공유해야 오류가 올바른 입력에 연결되고, 검증 결과에 따라 errors 또는 onSubmit으로 갈립니다. |
| 도표 설명 | register(name)가 현재 입력 값을 수집하며 같은 이름을 defaultValues와 schema에서 사용합니다. |
| 도표 설명 | handleSubmit이 제출 처리 |
| 도표 설명 | errors로 복귀 |
| 도표 설명 | defaultValues, register, schema의 필드 이름이 어긋나면 초기값·오류·제출 데이터가 서로 다른 키를 가리킵니다. 같은 이름으로 유지하되 클라이언트 통과를 서버 승인으로 간주하지 않습니다. |
| 장면 | 현재 관찰값 | 설명 | 변화 이유 |
|---|---|---|---|
| 동일 field 이름 | 연결: 같은 field 이름 / 입력: 현재 values | defaultValues·register·schema가 같은 username·email·password·confirmPassword를 연결합니다 | 필드 이름이 오류와 기본값을 잇습니다 |
| resolver 검사 | invalid: formState.errors / valid: onSubmitdata | handleSubmit이 yupResolver로 현재 값을 검사합니다 | 검증 실패는 API 요청으로 가지 않습니다 |
| 서버 검증 | client: valid data / server: 독립 검증 | 통과한 data로 API를 호출하되 서버의 판정을 기다립니다 | 권한·중복·무결성의 최종 판단은 서버가 합니다 |
위 그림은 방금 만든 연결을 그린 것입니다. 위쪽 칸은 username, email, password, confirmPassword 네 이름을 defaultValues와 register와 스키마가 똑같이 써야 한다는 뜻입니다. 아래쪽은 제출의 흐름입니다. register로 등록한 칸의 값을 handleSubmit이 모아 yupResolver(schema)에 넘기고, 걸리면 formState.errors로, 통과하면 onSubmit(data)로 갈립니다. 세 곳의 이름이 한 글자라도 다르면 어떻게 되는지는 연습 문제 2에서 확인합니다.
2단계: 검사 시점을 옵션으로 정하기
지금은 처음 제출하기 전까지 아무 검사도 하지 않습니다. 앞 글에서는 칸을 벗어날 때 검사하려고 리듀서에 액션을 더하고 handleBlur를 만들어 네 칸에 달았습니다. 여기서는 useForm에 옵션 한 줄을 더합니다.
} = useForm({
defaultValues,
resolver: yupResolver(schema),
mode: 'onBlur',
});mode는 처음 제출하기 전에 언제 검사할지를 정합니다. 기본값은 제출할 때만 검사하는 'onSubmit'이고, 'onBlur'로 두면 칸을 벗어날 때 그 칸을 검사합니다. register가 돌려준 onBlur가 이미 입력 칸에 달려 있으므로 JSX는 고칠 것이 없습니다.
한 번 제출한 뒤의 동작은 reValidateMode라는 다른 옵션이 정합니다. 기본값이 'onChange'여서, 제출한 뒤에는 오류가 있는 칸을 입력할 때마다 다시 검사합니다. 1단계의 체크포인트에서 세 번째 글자에 메시지가 사라진 것이 이 기본값 덕분입니다(React Hook Form의 useForm).
체크포인트: 저장하고 새로고침한 뒤 사용자 이름 칸에 mi를 입력하고 Tab 키로 넘어갑니다. 버튼을 누르지 않았는데도 "사용자 이름은 3자 이상이어야 합니다."가 나타납니다.
3단계: 서버에 보내고 결과에 따라 갈라 처리하기
이제 requestSignup을 연결합니다. 고칠 곳은 네 군데입니다. 불러오기를 더하고, useForm에서 꺼내는 것을 늘리고, onSubmit을 요청을 기다리는 함수로 바꾸고, 버튼 부분을 고칩니다.
import { useEffect } from 'react';
import { requestSignup } from '../api/signup';const {
register,
handleSubmit,
setError,
reset,
formState: { errors, isSubmitting, isSubmitSuccessful },
} = useForm({
defaultValues,
resolver: yupResolver(schema),
mode: 'onBlur',
});
useEffect(() => {
if (isSubmitSuccessful) {
reset();
}
}, [isSubmitSuccessful, reset]);
async function onSubmit(data) {
try {
const result = await requestSignup(data);
alert(`${result.username} 님, 가입이 완료되었습니다.`);
} catch (error) {
if (error.field) {
setError(error.field, { type: 'server', message: error.message });
} else {
setError('root.server', { type: 'server', message: error.message });
}
}
}{errors.root?.server && <p role="alert">{errors.root.server.message}</p>}
<button type="submit" disabled={isSubmitting}>
{isSubmitting ? '가입 중...' : '가입하기'}
</button>
<button type="button" onClick={() => reset()}>다시 쓰기</button>isSubmitting은 우리 훅에서 useState와 try/finally로 만들었던 바로 그 값입니다. onSubmit이 돌려준 Promise가 끝날 때까지 true로 있습니다.
실패했을 때가 앞 글보다 나아졌습니다. 우리 훅은 서버의 메시지를 모두 errors.submit 한 자리에 넣었습니다. 여기서는 setError의 첫 인자로 메시지를 붙일 자리를 고릅니다. requestSignup이 error.field에 'email'을 실어 보냈다면 setError('email', ...)이 되어, 메시지가 스키마의 오류와 똑같이 이메일 칸 아래에 나타납니다. 어느 칸의 문제인지 알 수 없는 실패는 'root.server'에 둡니다. root는 특정 칸이 아닌 폼 전체의 오류를 두라고 라이브러리가 마련해 둔 자리이고, 그 뒤의 server는 우리가 붙인 이름입니다(React Hook Form의 setError).
폼을 비우는 reset()은 onSubmit 안이 아니라 useEffect에서 부릅니다. React Hook Form 문서가 권하는 방식입니다. handleSubmit은 onSubmit이 끝난 뒤에 제출 상태를 정리하므로, onSubmit 안에서 폼을 비우면 그 정리와 순서가 엇갈립니다(React Hook Form의 reset). isSubmitSuccessful은 onSubmit이 오류를 던지지 않고 끝났고 그때 폼에 오류가 하나도 없으면 true가 됩니다. catch에서 setError를 부른 경우에는 오류가 남아 있으므로 false이고, 폼은 비워지지 않습니다. "다시 쓰기" 버튼을 onClick={reset}이 아니라 onClick={() => reset()}으로 적은 것도 눈여겨봅니다. reset은 첫 인자를 새 값으로 쓰기 때문에, 클릭 이벤트 객체가 인자로 들어가면 안 됩니다.
저장한 뒤 세 가지를 차례로 확인합니다. 사용자 이름은 mina, 두 비밀번호는 Abcdef1!로 두고 이메일만 바꿉니다.
체크포인트 1: 이메일에 [email protected]을 넣고 제출합니다. 버튼이 1초 동안 "가입 중..."으로 바뀌었다가 돌아오고, 이메일 칸 아래에 "이미 가입된 이메일입니다."가 나타납니다. 네 칸의 값은 그대로입니다. 이메일을 다른 주소로 고치면 그 칸을 스키마로 다시 검사하면서 서버가 준 메시지가 사라집니다.
체크포인트 2: 이메일에 [email protected]을 넣고 제출합니다. 이번에는 버튼 위에 "서버에 연결하지 못했습니다. 잠시 뒤 다시 시도하세요."가 나타나고 값은 그대로입니다. 이 메시지는 다음에 제출할 때 지워집니다.
체크포인트 3: 이메일을 [email protected]으로 고쳐 제출합니다. "mina 님, 가입이 완료되었습니다." 알림창을 닫으면 네 칸이 비워집니다.
회원가입 검증·제출·복구 상태 머신 — 상태 추적
제출 검증 때부터 isSubmitting과 isValidating은 겹칠 수 있고 server success만 reset합니다. 실패 field/root 오류·값 유지·교정/재시도를 busy·값·오류 상태로 보여 줍니다.
React · form state machine · server boundary
검증 통과 뒤에도 서버 실패와 복구 상태가 남습니다
제출 시 검증부터 버튼이 비활성화되고, invalid 입력은 errors로 돌아가며 valid 입력만 API 요청으로 진행합니다. 서버 성공은 reset()으로 끝나지만 field/global 오류는 setError()로 표시해 사용자가 교정한 뒤 다시 제출할 수 있어야 합니다.
입력·오류 교정
필드 값을 고치고 연결된 오류 메시지를 확인한 뒤 다시 제출합니다.
Yup 검증 중
제출 때 isSubmitting은 검증 전부터 켜집니다. busy가 버튼을 비활성화하고, invalid면 errors로 돌아가며 valid만 API 요청으로 갑니다.
API 요청과 버튼 비활성화
busy = isValidating || isSubmitting이면 버튼을 비활성화합니다. 통과한 값으로 요청하고 서버 응답을 기다립니다. 엄격한 중복 요청 차단은 따로 설계해야 합니다.
성공 뒤 reset()
서버가 승인한 뒤에만 폼 값과 관련 상태를 초기화하고 흐름을 끝냅니다.
Field 또는 global 오류
HTTP 실패·network 오류는 값을 유지합니다. 허용한 field만 setError로 연결하고 나머지는 root.server에 표시합니다. 필드 교정 또는 global 오류 해소 뒤 retry도 현재 값을 다시 검증합니다.
업무 단계를 표시한 그림이며 isSubmitting은 제출 검증부터 켜집니다. 버튼 disabled는 재클릭을 줄이며 엄격한 중복 요청 차단은 요청 guard·서버 idempotency를 별도로 설계합니다. 서버 오류 매핑은 실제 서비스를 위해 이 실습에 더한 부분입니다. 실제 백엔드의 오류 응답 형식에 맞춰 field 이름을 허용 목록으로 제한하고, 매핑할 수 없는 실패는 global 오류로 보여 줍니다.
이 예의 조건
- 도표의 전체 구조와 설명은 위 관계도와 표에서 볼 수 있습니다. 아래 표에도 도표의 관계·조건·라벨·설명·주석을 모았습니다.
- 두 칸의 위치는 고정입니다. 현재 상태는 그 순간의 값이고, 동작·이유는 그 조건에서의 판정과 변화 원인입니다. 독립 비교와 실패 분기는 별도 조건이므로 모든 분기를 한 요청의 실행 순서로 이어 읽지 않습니다.
관계도의 보충 설명
| 구분 | 내용 |
|---|---|
| 도표 설명 | 제출 시 검증부터 버튼이 비활성화되고, invalid 입력은 errors로 돌아가며 valid 입력만 API 요청으로 진행합니다. 서버 성공은 reset()으로 끝나지만 field/global 오류는 setError()로 표시해 사용자가 교정한 뒤 다시 제출할 수 있어야 합니다. |
| 도표 설명 | busy = isValidating || isSubmitting이면 버튼을 비활성화합니다. 통과한 값으로 요청하고 서버 응답을 기다립니다. 엄격한 중복 요청 차단은 따로 설계해야 합니다. |
| 장면 | 현재 관찰값 | 설명 | 변화 이유 |
|---|---|---|---|
| submit 검증 busy | busy: validating || submitting / button: disabled | isSubmitting은 검증 전부터 켜지고 isValidating과 겹칠 수 있습니다 | 두 Boolean을 배타적인 업무 단계로 표시하지 않습니다 |
| valid API 요청 | values: 유지 / isSubmitting: true | 통과한 현재 값으로 서버의 응답을 기다립니다 | 클라이언트 검증과 서버 승인은 다릅니다 |
| 결과와 복구 | 2xx: reset / 실패: 값 유지+교정/retry | 성공만 reset하고 실패는 field·root 오류와 값을 유지합니다 | 버튼 disabled가 서버 idempotency나 엄격한 중복 guard를 대신하지 않습니다 |
회원가입 검증·제출·복구 상태 머신 — 상태 추적
제출 검증 때부터 isSubmitting과 isValidating은 겹칠 수 있고 server success만 reset합니다. 실패 field/root 오류·값 유지·교정/재시도를 busy·값·오류 상태로 보여 줍니다.
React · form state machine · server boundary
검증 통과 뒤에도 서버 실패와 복구 상태가 남습니다
제출 시 검증부터 버튼이 비활성화되고, invalid 입력은 errors로 돌아가며 valid 입력만 API 요청으로 진행합니다. 서버 성공은 reset()으로 끝나지만 field/global 오류는 setError()로 표시해 사용자가 교정한 뒤 다시 제출할 수 있어야 합니다.
입력·오류 교정
필드 값을 고치고 연결된 오류 메시지를 확인한 뒤 다시 제출합니다.
Yup 검증 중
제출 때 isSubmitting은 검증 전부터 켜집니다. busy가 버튼을 비활성화하고, invalid면 errors로 돌아가며 valid만 API 요청으로 갑니다.
API 요청과 버튼 비활성화
busy = isValidating || isSubmitting이면 버튼을 비활성화합니다. 통과한 값으로 요청하고 서버 응답을 기다립니다. 엄격한 중복 요청 차단은 따로 설계해야 합니다.
성공 뒤 reset()
서버가 승인한 뒤에만 폼 값과 관련 상태를 초기화하고 흐름을 끝냅니다.
Field 또는 global 오류
HTTP 실패·network 오류는 값을 유지합니다. 허용한 field만 setError로 연결하고 나머지는 root.server에 표시합니다. 필드 교정 또는 global 오류 해소 뒤 retry도 현재 값을 다시 검증합니다.
업무 단계를 표시한 그림이며 isSubmitting은 제출 검증부터 켜집니다. 버튼 disabled는 재클릭을 줄이며 엄격한 중복 요청 차단은 요청 guard·서버 idempotency를 별도로 설계합니다. 서버 오류 매핑은 실제 서비스를 위해 이 실습에 더한 부분입니다. 실제 백엔드의 오류 응답 형식에 맞춰 field 이름을 허용 목록으로 제한하고, 매핑할 수 없는 실패는 global 오류로 보여 줍니다.
이 예의 조건
- 도표의 전체 구조와 설명은 위 관계도와 표에서 볼 수 있습니다. 아래 표에도 도표의 관계·조건·라벨·설명·주석을 모았습니다.
- 두 칸의 위치는 고정입니다. 현재 상태는 그 순간의 값이고, 동작·이유는 그 조건에서의 판정과 변화 원인입니다. 독립 비교와 실패 분기는 별도 조건이므로 모든 분기를 한 요청의 실행 순서로 이어 읽지 않습니다.
관계도의 보충 설명
| 구분 | 내용 |
|---|---|
| 도표 설명 | 제출 시 검증부터 버튼이 비활성화되고, invalid 입력은 errors로 돌아가며 valid 입력만 API 요청으로 진행합니다. 서버 성공은 reset()으로 끝나지만 field/global 오류는 setError()로 표시해 사용자가 교정한 뒤 다시 제출할 수 있어야 합니다. |
| 도표 설명 | busy = isValidating || isSubmitting이면 버튼을 비활성화합니다. 통과한 값으로 요청하고 서버 응답을 기다립니다. 엄격한 중복 요청 차단은 따로 설계해야 합니다. |
| 장면 | 현재 관찰값 | 설명 | 변화 이유 |
|---|---|---|---|
| submit 검증 busy | busy: validating || submitting / button: disabled | isSubmitting은 검증 전부터 켜지고 isValidating과 겹칠 수 있습니다 | 두 Boolean을 배타적인 업무 단계로 표시하지 않습니다 |
| valid API 요청 | values: 유지 / isSubmitting: true | 통과한 현재 값으로 서버의 응답을 기다립니다 | 클라이언트 검증과 서버 승인은 다릅니다 |
| 결과와 복구 | 2xx: reset / 실패: 값 유지+교정/retry | 성공만 reset하고 실패는 field·root 오류와 값을 유지합니다 | 버튼 disabled가 서버 idempotency나 엄격한 중복 guard를 대신하지 않습니다 |
위 그림은 완성한 폼이 거치는 상태를 한 장에 모은 것입니다. 입력하다가 제출하면 Yup 검사로 가고, 걸리면 입력으로 돌아오며, 통과하면 요청을 보냅니다. 응답이 성공이면 reset()으로 끝나고, 실패이면 setError()로 칸이나 root.server에 메시지를 붙인 채 값을 지키고 있다가 사용자가 고쳐 다시 제출하면 검사부터 되풀이합니다. 그림 아래의 isValidating은 검사하는 동안 true가 되는 formState의 값입니다. 그림은 이것까지 묶어 버튼을 막지만, isSubmitting이 검사가 시작되기 전부터 켜지므로 이 실습은 isSubmitting 하나만 썼습니다.
4단계: 손으로 만든 훅을 지우고 줄어든 것 세어 보기
src/hooks/useForm.js를 불러오는 파일이 이제 없습니다. 이 파일을 지웁니다. 앞 글의 연습 문제에서 LoginForm.jsx를 만들었다면 그 파일은 아직 우리 훅을 쓰고 있으므로, 연습 문제 3에서 옮긴 뒤에 지웁니다.
체크포인트: 파일을 지운 뒤에도 화면이 그대로 뜨고, 3단계의 세 가지 확인이 똑같이 통과합니다.
손으로 만든 것과 라이브러리가 준 것을 나란히 놓으면 다음과 같습니다.
| 손으로 만든 것 | 라이브러리에서 |
|---|---|
값을 담는 리듀서, handleChange, Field마다 value와 onChange | register('이름') 한 줄. 값은 DOM에 둠 |
validatePassword, validateSignup | Yup schema |
SET_FIELD_ERROR 액션, handleBlur, Field마다 onBlur | mode: 'onBlur' |
| 오류가 보이는 칸을 입력 중에 다시 검사 (연습 문제) | reValidateMode의 기본값 |
isSubmitting state와 try/finally | formState.isSubmitting |
서버 메시지를 errors.submit 한 곳에 | setError로 칸이나 root.server에 |
RESET_FORM 액션과 resetForm | reset |
| 검사에 걸린 첫 칸으로 포커스 옮기기 (만들지 않음) | 기본 동작 |
80줄 남짓한 useForm.js가 통째로 사라졌고, SignupForm.jsx에는 폼마다 달라지는 것만 남았습니다. 필드의 이름과 처음 값, 규칙, 성공과 실패에 할 일, 그리고 화면입니다. 줄지 않은 것도 있습니다. 라벨과 메시지를 입력 칸에 잇는 Field는 여전히 우리가 만든 것이고, 이미 가입된 이메일처럼 서버만 판단할 수 있는 규칙은 어떤 라이브러리를 써도 서버에 남습니다.
다를 때 먼저 볼 곳
| 증상 | 먼저 확인할 곳 |
|---|---|
| 화면이 뜨지 않고 불러오기에서 오류가 납니다. | 세 패키지를 모두 설치했는지, 리졸버를 '@hookform/resolvers/yup'에서 불러왔는지 봅니다. |
| 빈 폼을 제출해도 메시지가 보이지 않습니다. | useForm에 resolver: yupResolver(schema)를 넘겼는지, Field에 error={errors.이름?.message}를 넘겼는지 봅니다. |
| 우리 메시지 대신 브라우저의 말풍선이 뜹니다. | <form>에 noValidate가 있는지 봅니다. |
| 값을 입력했는데도 제출하면 "입력하세요" 메시지가 나옵니다. | register에 넘긴 이름이 스키마의 이름과 같은지, Field가 나머지 props를 <input>에 펼쳐 넣는지 봅니다. React 18 이하에서는 함수 컴포넌트가 ref를 props로 받지 못하므로 이 Field를 그대로 쓸 수 없습니다. |
| "다시 쓰기"를 누르면 폼이 이상해집니다. | onClick={reset}으로 적지 않았는지 봅니다. onClick={() => reset()}이어야 합니다. |
| 가입에 성공했는데 폼이 비워지지 않습니다. | formState에서 isSubmitSuccessful을 꺼냈는지, useEffect의 조건과 의존성 배열을 봅니다. |
| 가입에 실패했는데 폼이 비워집니다. | catch 안에서 setError를 부르는지 봅니다. 오류가 남지 않으면 성공한 제출로 처리됩니다. |
완성 파일 전체
src/components/SignupForm.jsx
import { useEffect } from 'react';
import { useForm } from 'react-hook-form';
import { yupResolver } from '@hookform/resolvers/yup';
import * as yup from 'yup';
import Field from './Field';
import { requestSignup } from '../api/signup';
const defaultValues = {
username: '',
email: '',
password: '',
confirmPassword: '',
};
const schema = yup.object({
username: yup
.string()
.trim()
.required('사용자 이름을 입력하세요.')
.min(3, '사용자 이름은 3자 이상이어야 합니다.'),
email: yup
.string()
.required('이메일을 입력하세요.')
.email('이메일 형식이 올바르지 않습니다.'),
password: yup
.string()
.required('비밀번호를 입력하세요.')
.min(8, '비밀번호는 8자 이상이어야 합니다.')
.matches(/[A-Z]/, '대문자를 하나 이상 넣어 주세요.')
.matches(/[a-z]/, '소문자를 하나 이상 넣어 주세요.')
.matches(/[0-9]/, '숫자를 하나 이상 넣어 주세요.'),
confirmPassword: yup
.string()
.required('비밀번호를 한 번 더 입력하세요.')
.oneOf([yup.ref('password')], '비밀번호가 일치하지 않습니다.'),
});
export default function SignupForm() {
const {
register,
handleSubmit,
setError,
reset,
formState: { errors, isSubmitting, isSubmitSuccessful },
} = useForm({
defaultValues,
resolver: yupResolver(schema),
mode: 'onBlur',
});
useEffect(() => {
if (isSubmitSuccessful) {
reset();
}
}, [isSubmitSuccessful, reset]);
async function onSubmit(data) {
try {
const result = await requestSignup(data);
alert(`${result.username} 님, 가입이 완료되었습니다.`);
} catch (error) {
if (error.field) {
setError(error.field, { type: 'server', message: error.message });
} else {
setError('root.server', { type: 'server', message: error.message });
}
}
}
return (
<form onSubmit={handleSubmit(onSubmit)} noValidate>
<Field
label="사용자 이름"
error={errors.username?.message}
{...register('username')}
/>
<Field
label="이메일"
type="email"
error={errors.email?.message}
{...register('email')}
/>
<Field
label="비밀번호"
type="password"
error={errors.password?.message}
{...register('password')}
/>
<Field
label="비밀번호 확인"
type="password"
error={errors.confirmPassword?.message}
{...register('confirmPassword')}
/>
{errors.root?.server && <p role="alert">{errors.root.server.message}</p>}
<button type="submit" disabled={isSubmitting}>
{isSubmitting ? '가입 중...' : '가입하기'}
</button>
<button type="button" onClick={() => reset()}>다시 쓰기</button>
</form>
);
}App.jsx, Field.jsx, signup.js는 이 글 처음의 "그대로 쓰는 세 파일"과 같습니다.
더 해 보기
완성한 폼에 스스로 붙여 볼 기능입니다. 해설은 없고 방향만 적습니다.
- 약관 동의 체크박스를 달고, 체크하지 않으면 "약관에 동의해야 합니다."를 보여 주며 가입을 막습니다. 스키마에서는
yup.boolean()과oneOf를 살펴봅니다.defaultValues와register, 스키마 세 곳에 같은 이름을 더해야 합니다. - 두 비밀번호를 똑같이 채운 뒤 비밀번호만 고치고 칸을 벗어나도, 지금은 비밀번호 확인의 메시지가 나타나지 않습니다. 앞 글에서 본 어긋남이 그대로 남아 있는 것입니다.
register의 두 번째 인자에 줄 수 있는deps옵션을 React Hook Form의 register 문서에서 찾아, 비밀번호를 검사할 때 비밀번호 확인도 함께 검사되게 합니다. signup.js를 고쳐 사용자 이름이admin이면 "이미 쓰이고 있는 이름입니다."로 실패하게 합니다.error.field를 알맞게 주면SignupForm.jsx를 한 줄도 고치지 않고 메시지가 사용자 이름 칸 아래에 나타나야 합니다.
더 깊이: 글자를 입력해도 폼이 다시 렌더링되지 않는 이유
앞의 세 글에서 만든 폼은 글자 하나를 입력할 때마다 SignupForm 전체가 다시 렌더링되었습니다. 입력값이 state였기 때문입니다. React Hook Form은 register로 등록한 입력의 값을 state가 아니라 DOM에 두고 ref로 읽으므로, 입력만으로는 컴포넌트를 다시 렌더링할 이유가 없습니다. 그래서 register로 등록한 입력에 value를 함께 넘기지 않습니다. 날짜 선택기처럼 value와 onChange로만 다룰 수 있는 외부 컴포넌트는 register 대신 라이브러리의 Controller로 감싸 연결합니다.
formState에도 같은 생각이 들어 있습니다. React Hook Form의 formState 문서는 formState가 프록시(Proxy)로 감싸여 있고, 렌더링하기 전에 읽은 속성의 변화만 다시 렌더링을 일으킨다고 설명합니다. 이 글에서 errors, isSubmitting, isSubmitSuccessful을 useForm을 부르는 자리에서 구조 분해로 꺼낸 것은 그 때문입니다. 쓰지 않는 값은 꺼내지 않는 편이 렌더링을 줄입니다.
정리
- 필드 이름 하나를
defaultValues와register, Yup 스키마가 함께 씁니다. 세 곳의 이름이 같아야 값과 오류가 같은 칸에 붙습니다. handleSubmit은 지금 값을yupResolver(schema)로 검사해, 걸리면formState.errors에 메시지를 두고 통과한 값만onSubmit에 넘깁니다.- 처음 제출하기 전의 검사 시점은
mode로, 제출한 뒤의 다시 검사는reValidateMode로 정합니다. - 서버가 거절한 이유는
setError로 해당 칸에 붙이고, 칸을 알 수 없으면root아래에 둡니다. reset()은 제출이 성공했을 때만,isSubmitSuccessful을 보는useEffect에서 부릅니다. 실패했을 때는 입력을 지키고 고칠 곳을 보여 줍니다.
연습 문제
1. 메시지가 사라지는 때
완성한 폼을 새로고침한 뒤 이메일 칸에 mina를 입력하고 Tab으로 칸을 벗어나면 "이메일 형식이 올바르지 않습니다."가 나타납니다. 이메일 칸으로 돌아가 @example.com을 이어 입력하는 동안 이 메시지는 언제 사라질까요? "가입하기"를 한 번 누른 뒤에 같은 일을 하면 어떻게 달라질까요?
해설 보기
처음 제출하기 전에는 주소를 다 입력해도 메시지가 남아 있다가, 칸을 벗어나는 순간 사라집니다. 처음 제출하기 전의 검사 시점은 mode: 'onBlur'가 정하므로, 입력하는 동안에는 다시 검사하지 않습니다.
"가입하기"를 한 번 누른 뒤에는 reValidateMode의 기본값 'onChange'가 적용됩니다. 글자를 입력할 때마다 그 칸을 다시 검사하므로, 주소가 올바른 모양이 되는 순간 칸을 벗어나지 않아도 메시지가 사라집니다.
2. 무엇을 넣어도 통과하지 못하는 칸 고치기
비밀번호 확인 칸을 다음처럼 등록했습니다. 비밀번호 칸과 확인 칸에 모두 Abcdef1!를 넣었는데도 제출할 때마다 "비밀번호가 일치하지 않습니다."가 나옵니다. 이유를 설명하고 고쳐 보세요.
<Field
label="비밀번호 확인"
type="password"
error={errors.confirmPassword?.message}
{...register('passwordConfirm')}
/>해설 보기
register에 넘긴 이름은 passwordConfirm인데, 스키마와 defaultValues는 confirmPassword라는 이름을 씁니다. 사용자가 입력한 값은 passwordConfirm이라는 이름으로 모이고, 스키마가 검사하는 confirmPassword는 defaultValues에 적힌 빈 문자열 그대로입니다. 비밀번호 Abcdef1!와 빈 문자열이 다르므로 oneOf 검사에 걸립니다. 이 스키마에서는 oneOf 검사가 문자열의 required 검사보다 먼저 실패해 "비밀번호가 일치하지 않습니다."가 나옵니다. 메시지는 errors.confirmPassword에 들어가고, 이 Field가 바로 그 값을 error로 받고 있으므로 확인 칸 아래에 보입니다.
register의 이름을 나머지 두 곳과 맞춥니다.
{...register('confirmPassword')}본문의 첫 번째 그림이 말한 것이 이것입니다. 필드 이름은 defaultValues, register, 스키마 세 곳을 잇는 유일한 끈이어서, 한 곳만 달라져도 값과 규칙이 서로 다른 칸을 보게 됩니다.
3. 로그인 폼을 라이브러리로 만들기
src/components/LoginForm.jsx에 React Hook Form과 Yup으로 로그인 폼을 만들어 보세요. 폼 상태 커스텀 훅과 라이브러리의 연습 문제에서 만든 파일이 있다면 그 내용을 바꿉니다.
- 이메일과 비밀번호 두 칸, "로그인" 버튼이 있습니다.
Field를 그대로 씁니다. - 이메일이 비어 있으면 "이메일을 입력하세요.", 형식이 틀리면 "이메일 형식이 올바르지 않습니다."가 보입니다. 비밀번호가 비어 있으면 "비밀번호를 입력하세요."가 보입니다.
- 칸을 벗어날 때 그 칸을 검사합니다.
- 두 칸을 올바르게 채워 제출하면 "(입력한 이메일) 계정으로 로그인합니다."라는 알림창이 뜹니다.
해설 보기
회원가입 폼에서 필드와 규칙을 줄이고, 서버 요청과 관련된 부분을 빼면 됩니다.
import { useForm } from 'react-hook-form';
import { yupResolver } from '@hookform/resolvers/yup';
import * as yup from 'yup';
import Field from './Field';
const defaultValues = { email: '', password: '' };
const schema = yup.object({
email: yup
.string()
.required('이메일을 입력하세요.')
.email('이메일 형식이 올바르지 않습니다.'),
password: yup.string().required('비밀번호를 입력하세요.'),
});
export default function LoginForm() {
const {
register,
handleSubmit,
formState: { errors },
} = useForm({
defaultValues,
resolver: yupResolver(schema),
mode: 'onBlur',
});
function onSubmit(data) {
alert(`${data.email} 계정으로 로그인합니다.`);
}
return (
<form onSubmit={handleSubmit(onSubmit)} noValidate>
<Field
label="이메일"
type="email"
error={errors.email?.message}
{...register('email')}
/>
<Field
label="비밀번호"
type="password"
error={errors.password?.message}
{...register('password')}
/>
<button type="submit">로그인</button>
</form>
);
}App.jsx에서 SignupForm 대신 LoginForm을 불러와 그리고 확인합니다. 이메일 칸을 비운 채 Tab으로 넘어가면 "이메일을 입력하세요."가, mina를 넣고 넘어가면 "이메일 형식이 올바르지 않습니다."가 나타납니다. 두 칸을 채워 제출하면 알림창이 뜹니다.
손으로 만든 훅을 쓰던 LoginForm과 견주어 보면, 검사 함수가 스키마로 바뀌었고 Field에 넘기던 value와 onChange가 register 한 줄이 되었습니다. 이 파일까지 옮겼다면 src/hooks/useForm.js를 불러오는 곳이 남지 않으므로 지워도 됩니다.
이것으로 9장을 마칩니다. 이메일 입력 하나를 state로 제어하는 데서 시작해, 네 필드의 값과 오류를 리듀서와 커스텀 훅으로 정리하고, 검사 규칙과 시점을 손으로 만들어 본 뒤, 같은 폼을 React Hook Form과 Yup으로 옮겼습니다. 라이브러리의 옵션 하나하나가 무엇을 대신하는지는 그 일을 손으로 해 본 만큼 보입니다. 다음 장의 React Developer Tools 사용법부터는 성능을 다루며, 컴포넌트가 언제 얼마나 다시 렌더링되는지 측정하는 것으로 시작합니다.