본문으로 건너뛰기

V7에서 V8로 마이그레이션(BETA)

설치​

npm install react-hook-form@beta

React Compiler​

V8에서는 React Compiler를 정식으로 지원합니다. 추가 설정은 필요하지 않으며, 이제 React Hook Form과 바로 호환됩니다.

단순 필드 배열​

V8의 타입은 단순 필드 배열을 지원하므로 useFieldArray를 사용할 때 더 간단한 데이터 구조를 쓸 수 있습니다.

// Before (V7) — each row had to be an object
useFieldArray({ name: "items" }) // items: { value: string }[]

// After (V8) — primitive values type-check
useFieldArray({ name: "items" }) // items: string[]

참고: 현재 베타에서는 타입만 개선되었습니다. 내부적으로 fields는 여전히 각 항목을 { ...field, key }로 펼치므로 원시값 배열 항목에서는 예상대로 동작하지 않습니다. 프로덕션에서 이 기능에 의존하기 전에 원시값 items: string[] 배열의 렌더링 동작을 확인하세요.

주요 변경 사항​

V7에서 업그레이드할 때 다음 변경 사항에 맞춰 기존 코드를 업데이트해야 합니다.

입력 ref​

register가 반환하는 ref는 변경되지 않았습니다. 여전히 실제 DOM 요소를 받는 콜백 ref입니다. 이번 변경은 Controller와 useController의 field.ref에 관한 것입니다. V7의 field.ref는 focus, select, setCustomValidity, reportValidity만 노출하는 부분 프록시 객체였습니다. V8의 field.ref는 실제 DOM 요소이므로 실제 노드의 모든 메서드와 속성을 사용할 수 있습니다.

const { field } = useController({ name: "firstName", control })

// Before (V7) — field.ref only exposed a fixed set of methods
field.ref.appendChild // ❌ not available

// After (V8) — field.ref is the actual input element
field.ref.appendChild // ✅ available, like any other DOM node

자세한 내용은 #12773을 참고하세요.

useFieldArray​

useFieldArray에는 두 가지 변경 사항이 적용됩니다.

id가 key로 변경됨

내부 렌더링 식별자의 이름이 id에서 key로 변경되었습니다. 구조 분해한 필드 참조를 업데이트하세요.

const { fields, append } = useFieldArray({ name: "items" })

// fields[0].key is the unique render identifier (was fields[0].id)

참고: 여전히 id나 key를 데이터로 추가할 수 있으며, 어느 쪽도 렌더링 키에는 영향을 주지 않습니다.

append({
  key: "custom-key", // stored as field data, does not override the render key
  id: "custom-id", // stored as field data, does not override the render key
})

fields[0].key // unique id used for re-render (auto-generated)

keyName prop 제거됨

keyName 옵션이 useFieldArray에서 제거되었습니다. 렌더링 키는 항상 key입니다.

Watch 컴포넌트​

나머지 API와 일관성을 맞추기 위해 <Watch /> 컴포넌트 prop names의 이름이 name으로 변경되었습니다.

// Before (V7)
<Watch names={["firstName", "lastName"]} />

// After (V8)
<Watch name={["firstName", "lastName"]} />

watch 콜백 API​

watch 구독 콜백 오버로드가 내보내던 타입(WatchObserver)이 공개 API에서 제거되었습니다. 현재 베타에서도 콜백은 런타임에 동작하지만 이 타입을 가져와 사용했다면 해당 이름 있는 타입을 더 이상 사용할 수 없습니다. 앞으로는 이 패턴을 지원하며 타입이 완전히 지정된 subscribe를 대신 사용하세요.

// Before (V7)
watch((value, { name, type }) => console.log(value))

// After (V8) — use subscribe
subscribe({
  formState: { values: true },
  callback: ({ values }) => console.log(values),
})

setValue​

현재 베타에서 setValue는 V7과 마찬가지로 여전히 useFieldArray 필드를 직접 업데이트합니다. 이 절에서는 아직 출시되지 않은 예정된 변경 사항을 설명합니다. 전체 필드 배열을 덮어써야 한다면 replace 메서드를 useFieldArray에서 사용하는 것이 V7과 V8 모두에서 권장됩니다.

const { replace } = useFieldArray({ name: "items" })
replace(newItems)

자세한 내용은 setValue와 useFieldArray 문서를 참고하세요.