본문으로 건너뛰기

FieldArray

</> FieldArray: FieldArrayProps v7.81.0부터​

useFieldArray 훅을 기반으로 한 컴포넌트로, 동적 필드 배열을 헤드리스/제어 컴포넌트로 다룰 때 유용합니다. 모든 prop은 useFieldArray와 같으며, 여기에 훅의 반환값을 받는 render prop이 추가됩니다.

<FieldArray
  control={control}
  name="test"
  render={({ fields }) =>
    fields.map((field, index) => (
      <input key={field.id} {...register(`test.${index}.value`)} />
    ))
  }
/>

Props(속성)​

이름타입필수설명
renderFunction✓useFieldArray가 반환하는 것과 같은 객체(fields, append, prepend, insert, remove, swap, move, update, replace)를 받아 React 요소를 반환하는 렌더 prop 함수입니다.
namestring✓필드 배열 이름입니다. 참고: 동적 이름은 지원하지 않습니다.
controlObjectcontrol 객체이며 useForm이 제공합니다. FormProvider를 사용한다면 선택 사항입니다.
shouldUnregisterboolean마운트 해제 후 필드 배열의 등록을 해제할지 지정합니다.
disabledboolean전체 필드 배열을 비활성화합니다. true이면 fields의 항목은 유지되지만 각 항목의 disabled 속성이 true가 되고, 모든 변경 메서드(append, prepend, insert, remove, swap, move, update, replace)는 아무 작업도 하지 않으며 배열의 내부 구독도 설정되지 않습니다. 판별 유니온 폼 구조에서 필드 배열을 조건부로 활성화할 때 유용합니다.
keyNamestring = "id"key prop으로 사용할 자동 생성 식별자 속성의 이름입니다. 이 prop은 더 이상 필요하지 않으며 다음 메이저 버전에서 제거될 예정입니다.
rulesObject검증 rules API는 register와 같으며 required, minLength, maxLength, validate를 포함합니다. 검증 오류가 발생하면 root 속성이 formState.errors?.<name>?.root에 추가됩니다(예: formState.errors?.test?.root는 이름이 test인 필드 배열). 타입은 FieldError입니다. 중요: 이는 내장 검증에만 적용됩니다.

반환값​

다음 표는 render prop 함수에 전달되는 객체를 설명합니다. 이 객체는 useFieldArray의 반환값과 같습니다.

이름타입설명
fieldsobject & { id: string }이 object에는 컴포넌트의 defaultValue와 key가 들어 있습니다. 훅 수준의 disabled prop을 설정하면 모든 항목의 disabled 속성에 반영되지만 등록된 입력에는 자동으로 전달되지 않으므로 직접 입력에 펼쳐야 합니다.
append(obj: object | object[], focusOptions) => void필드 끝에 입력을 추가하고 포커스합니다. 이 작업 중 입력값이 등록됩니다. 중요: append 데이터는 필수이며 일부만 제공할 수 없습니다.
prepend(obj: object | object[], focusOptions) => void필드 시작 부분에 입력을 추가하고 포커스합니다. 이 작업 중 입력값이 등록됩니다. 중요: prepend 데이터는 필수이며 일부만 제공할 수 없습니다.
insert(index: number, value: object | object[], focusOptions) => void지정한 위치에 입력을 삽입하고 포커스합니다. 중요: insert 데이터는 필수이며 일부만 제공할 수 없습니다.
swap(from: number, to: number) => void입력 위치를 서로 바꿉니다.
move(from: number, to: number) => void입력을 다른 위치로 옮깁니다.
update(index: number, obj: object) => void지정한 위치의 입력을 업데이트합니다. 업데이트된 필드는 마운트 해제된 후 다시 마운트됩니다. 이 동작을 원하지 않으면 setValue API를 대신 사용하세요. 중요: update 데이터는 필수이며 일부만 제공할 수 없습니다.
replace(obj: object[]) => void전체 필드 배열 값을 바꿉니다.
remove(index?: number | number[]) => void지정한 위치의 입력을 제거합니다. 인덱스를 제공하지 않으면 모두 제거합니다.
예시:​
import { useForm, FieldArray } from "react-hook-form"

type FormValues = {
  test: { value: string }[]
}

export default function App() {
  const { control, register, handleSubmit } = useForm<FormValues>({
    defaultValues: {
      test: [{ value: "" }],
    },
  })

  return (
    <form onSubmit={handleSubmit((data) => console.log(data))}>
      <FieldArray
        control={control}
        name="test"
        render={({ fields, append, remove }) => (
          <>
            {fields.map((field, index) => (
              <div key={field.id}>
                <input {...register(`test.${index}.value`)} />
                <button type="button" onClick={() => remove(index)}>
                  Delete
                </button>
              </div>
            ))}
            <button type="button" onClick={() => append({ value: "" })}>
              Append
            </button>
          </>
        )}
      />
      <input type="submit" />
    </form>
  )
}