본문으로 건너뛰기

register

</> register: UseFormRegister​

이 메서드를 사용하면 React Hook Form에 input 또는 select 요소를 등록하고 검증 규칙을 적용할 수 있습니다. 검증 규칙은 모두 HTML 표준을 기반으로 하며 사용자 정의 검증 메서드도 사용할 수 있습니다.

Props​

이름타입설명
namestring입력 이름입니다.
optionsRegisterOptions입력 동작입니다.

반환값​

이름타입설명
refReact.Refhook form을 입력에 연결하는 데 사용하는 React 요소 ref입니다.
namestring등록하는 입력의 이름입니다.
onChangeChangeHandler입력의 change 이벤트를 구독하는 onChange prop입니다.
onBlurChangeHandler입력의 blur 이벤트를 구독하는 onBlur prop입니다.
minstring | numberv7.21.0부터 progressive가 true일 때만 존재하며 설정된 min 규칙을 반영합니다(없으면 undefined).
maxstring | numberv7.21.0부터 progressive가 true일 때만 존재하며 설정된 max 규칙을 반영합니다(없으면 undefined).
maxLengthnumberv7.21.0부터 progressive가 true일 때만 존재하며 설정된 maxLength 규칙을 반영합니다(없으면 undefined).
minLengthnumberv7.21.0부터 progressive가 true일 때만 존재하며 설정된 minLength 규칙을 반영합니다(없으면 undefined).
patternstringv7.21.0부터 progressive가 true일 때만 존재하며 설정된 pattern 규칙을 반영합니다(없으면 undefined).
requiredbooleanv7.21.0부터 progressive가 true일 때만 존재하며 설정된 required 규칙을 반영합니다(없으면 false).
disabledbooleanv7.21.0부터 선택 사항. disabled 옵션이 설정되었을 때 존재합니다.

옵션​

register 옵션을 선택하면 아래 API 표가 업데이트됩니다.

이름설명
required
boolean
폼을 제출하기 전에 입력에 값이 있어야 함을 나타냅니다.

참고: 이 설정은 필수 입력 검증을 위한 웹 제약 조건 API와 일치합니다. 객체 또는 배열 입력 타입에는 대신 validate 함수를 사용합니다.
maxLength
number
이 입력에서 허용할 값의 최대 길이입니다.
minLength
number
이 입력에서 허용할 값의 최소 길이입니다.
max
number
이 입력에서 허용할 최댓값입니다.
min
number
이 입력에서 허용할 최솟값입니다.
pattern
RegExp
입력의 정규식 패턴입니다.

참고: RegExp에 /g 플래그를 사용하면 마지막으로 일치한 인덱스를 추적합니다.
validate
Function |
Record<string, Function>
validate 함수는 required 속성에 포함된 다른 검증 규칙에 의존하지 않고 독립적으로 실행됩니다. 이 함수는 필드 값과 (v7.42.0부터 선택적으로 두 번째 인수로 전체 폼 값)을 받고 다음 중 하나를 반환해야 합니다.
  • true 또는 undefined — 필드가 유효합니다(둘은 동일하게 처리되며 명시적인 return true가 일반적이지만 필수는 아닙니다).
  • string — 필드가 유효하지 않으며 문자열을 오류 메시지로 사용합니다.
  • false — 사용자 정의 메시지 없이 필드가 유효하지 않습니다(일반 오류 사용).
각각 고유한 오류 메시지를 가진 여러 독립 검증을 실행하려면 이름 있는 함수의 객체를 전달합니다.

참고: 객체 또는 배열 입력 데이터에는 validate 함수를 사용하는 것이 좋습니다. 다른 규칙은 대부분 문자열, 문자열 배열, 숫자, 불리언에 적용되기 때문입니다.
valueAsNumber
boolean
일반적으로 Number를 반환합니다. 문제가 생기면 NaN을 반환합니다.
  • valueAs 처리는 검증 전에 수행됩니다.
  • 데이터 조작 없이 number 입력에만 적용됩니다.
  • defaultValue 또는 defaultValues를 변환하지 않습니다.
valueAsDate
boolean
일반적으로 Date를 반환합니다. 문제가 생기면 Invalid Date를 반환합니다.
  • valueAs 처리는 검증 전에 수행됩니다.
  • 입력에만 적용됩니다.
  • defaultValue 또는 defaultValues를 변환하지 않습니다.
setValueAs
<T>(value: any) => T
함수를 거친 입력 값을 반환합니다.
  • valueAs 처리는 검증 전에 수행됩니다. 또한 setValueAs는 valueAsNumber 또는 valueAsDate 중 하나가 true이면 무시됩니다.
  • 텍스트 입력에만 적용됩니다.
  • defaultValue 또는 defaultValues를 변환하지 않습니다.
disabled
boolean = false
v7.13.0부터 disabled를 true로 설정하면 입력 값이 undefined가 되고 입력 컨트롤이 비활성화됩니다.
  • disabled prop은 내장 검증 규칙도 생략합니다.
  • 스키마 검증에서는 입력 또는 context 객체가 반환한 undefined 값을 활용할 수 있습니다.
onChange
(e: SyntheticEvent) => void
v7.16.0부터 change 이벤트에서 호출할 onChange 함수 이벤트입니다.
onBlur
(e: SyntheticEvent) => void
v7.16.0부터 blur 이벤트에서 호출할 onBlur 함수 이벤트입니다.
value
unknown
v7.8.0부터 등록된 입력에 value를 설정합니다. 이 prop은 useEffect 안에서 사용하거나 한 번만 호출해야 합니다. 다시 실행할 때마다 제공한 입력 값이 업데이트되거나 덮어써집니다.
shouldUnregister
boolean
언마운트 후 입력이 등록 해제되고 defaultValues도 제거됩니다.

참고: useFieldArray와 함께 사용할 때는 이 prop을 피해야 합니다. 입력 언마운트/리마운트 및 순서 변경 후 unregister 함수가 호출되기 때문입니다.
deps
string | string[]
v7.14.0부터 이 필드 자체의 검증이 실행되면(예: 등록된 onChange/onBlur를 통해) deps에 나열한 필드도 다시 검증됩니다. trigger()를 수동으로 호출할 때는 deps를 적용하지 않습니다.
예제​

input 또는 select 등록

import { useForm } from "react-hook-form"

export default function App() {
  const { register, handleSubmit } = useForm({
    defaultValues: {
      firstName: "",
      lastName: "",
      category: "",
      checkbox: [],
      radio: "",
    },
  })

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <input
        {...register("firstName", { required: true })}
        placeholder="First name"
      />

      <input
        {...register("lastName", { minLength: 2 })}
        placeholder="Last name"
      />

      <select {...register("category")}>
        <option value="">Select...</option>
        <option value="A">Category A</option>
        <option value="B">Category B</option>
      </select>

      <input {...register("checkbox")} type="checkbox" value="A" />
      <input {...register("checkbox")} type="checkbox" value="B" />
      <input {...register("checkbox")} type="checkbox" value="C" />

      <input {...register("radio")} type="radio" value="A" />
      <input {...register("radio")} type="radio" value="B" />
      <input {...register("radio")} type="radio" value="C" />

      <input type="submit" />
    </form>
  )
}

사용자 정의 비동기 검증

import { useForm } from "react-hook-form"
import { checkProduct } from "./service"

export default function App() {
  const { register, handleSubmit } = useForm()

  return (
    <form onSubmit={handleSubmit(console.log)}>
      <select
        {...register("category", {
          required: true,
        })}
      >
        <option value="">Select...</option>
        <option value="A">Category A</option>
        <option value="B">Category B</option>
      </select>

      <input
        type="text"
        {...register("product", {
          validate: {
            checkAvailability: async (product, { category }) => {
              if (!category) return "Choose a category"
              if (!product) return "Specify your product"
              const isInStock = await checkProduct(category, product)
              return isInStock || "There is no such product"
            },
          },
        })}
      />

      <input type="submit" />
    </form>
  )
}

동영상​

팁​

구조 분해 할당​

const { onChange, onBlur, name, ref } = register('firstName');
// Include a type check against the field path with the name you have supplied.

<input
  onChange={onChange} // assign onChange event
  onBlur={onBlur} // assign onBlur event
  name={name} // assign name prop
  ref={ref} // assign ref prop
/>
// same as above
<input {...register('firstName')} />

사용자 정의 register​

useEffect로 입력을 등록하고 가상 입력으로 취급할 수도 있습니다. 제어 컴포넌트에서는 이 과정을 처리하는 커스텀 훅 useController와 Controller 컴포넌트를 제공합니다.

필드를 수동으로 등록한다면 setValue로 입력 값을 업데이트해야 합니다.

register("firstName", { required: true, minLength: 8 })
;<TextInput onTextChange={(value) => setValue("firstName", value)} />

innerRef, inputRef 사용 방법​

사용자 정의 입력 컴포넌트가 ref를 올바르게 노출하지 않는다면 다음 방법으로 동작하게 할 수 있습니다.

// not working, because ref is not assigned
<TextInput {...register('test')} />

const firstName = register('firstName', { required: true })
<TextInput
  name={firstName.name}
  onChange={firstName.onChange}
  onBlur={firstName.onBlur}
  inputRef={firstName.ref} // you can achieve the same for different ref names such as innerRef
/>