Skip to content
♥

register

비제어/제어 입력 필드 등록(register)

</> register: (name: string, options?: RegisterOptions) => ({ ref, name, onChange, onBlur })

이 메서드를 사용하면 입력 또는 선택 요소를 등록(register)하고 React Hook Form에 유효성 검사 규칙을 적용할 수 있습니다. 유효성 검사 규칙은 모두 HTML 표준을 기반으로 하며 사용자 정의 유효성 검사 메서드도 허용합니다.

Props

NameTypeDescription
namestring입력 필드의 이름.
optionsRegisterOptions입력 필드의 동작.

Return

NameTypeDescription
refReact.refhook form을 입력 필드에 연결하기 위해 사용하는 React 엘리먼트 ref.
namestring등록(registered)된 입력의 이름.
onChangeChangeHandleronChange 속성은 입력 변경 이벤트를 구독합니다.
onBlurChangeHandleronBlur 속성은 입력 블러(blur) 이벤트를 구독합니다.
NOTE

제출된 값은 다음과 같은 형태로 표시됩니다:

Input NameSubmit Result
register("firstName"){ firstName: value }
register("name.firstName"){ name: { firstName: value } }
register("name.firstName.0"){ name: { firstName: [ value ] } }

Options

By selecting the register option, the API table below will get updated.

NameDescription
ref
React.Ref
React 엘리먼트 ref
required
boolean
폼을 제출하기 전에 해당 입력 필드에 값이 있어야 함을 나타냅니다.

참고: 이 구성은 필수 입력 유효성 검사를 위한 웹 제한 API와 일치합니다. 객체나 배열 유형의 입력인 경우 validate 함수를 대신 사용하세요.
maxLength
number
이 입력에서 허용할 값의 최대 길이.
minLength
number
이 입력에서 허용할 값의 최소 길이.
max
number
이 입력에서 허용할 최대값.
min
number
이 입력에서 허용할 최소값.
pattern
RegExp
입력에 대한 정규식 패턴.

참고: /g 플래그를 가진 RegExp 객체는 일치가 발생한 마지막 인덱스를 추적합니다.
validate
Function |
Record<string, Function>
Validate 함수는 required 속성에 포함된 다른 유효성 검사 규칙에 의존하지 않고 독립적으로 실행됩니다.

참고: 다른 규칙들은 주로 문자열, 문자열 배열(string[]), 숫자 및 boolean 데이터 타입에 적용되기 때문에 객체 또는 배열 입력 데이터의 경우 유효성 검사에 validate 함수를 사용하는 것이 권장됩니다.
valueAsNumber
boolean
보통 숫자를 반환합니다. 문제가 발생하면 NaN 이 반환됩니다.
  • valueAs 프로세스는 유효성 검사 전에 발생합니다.
  • 숫자 입력 필드에만 적용되며, 데이더 조작 없이 동작합니다.
  • defaultValue나 defaultValues는 변환되지 않습니다.
valueAsDate
boolean
보통 Date객체를 반환합니다. 문제가 발생하면 Invalid Date가 반환됩니다.
  • valueAs 프로세스는 유효성 검사 전에 발생합니다.
  • 입력 필드에만 적용됩니다.
  • defaultValue나 defaultValues는 변환되지 않습니다.
setValueAs
<T>(value: any) => T
함수를 실행하여 입력값을 반환합니다.
  • valueAs 프로세스는 유효성 검사 전에 발생합니다. 또한, valueAsNumber나 valueAsDate가 true인 경우 setValueAs는 무시됩니다.
  • 텍스트 입력 필드에만 적용됩니다.
  • defaultValue나 defaultValues는 변환되지 않습니다.
disabled
boolean = false
disabled를 true로 설정하면 입력 값이 undefined가 되며 입력 컨트롤이 비활성화됩니다.
  • disabled 속성은 내장된 유효성 검사 규칙도 제외합니다.
  • 스키마 유효성 검사를 위해, 입력 또는 컨텍스트 객체에서 반환된 undefined 값을 활용할 수 있습니다.
onChange
(e: SyntheticEvent) => void
변경 이벤트에서 호출될 onChange 함수.
onBlur
(e: SyntheticEvent) => void
블러(blur) 이벤트에서 호출될 onBlur 함수.
value
unknown
등록된(registered) 입력의 값을 설정합니다. 이 속성은 useEffect 내부에서 사용하거나 한 번만 호출해야 하며, 재실행할 때마다 입력 값을 업데이트하거나 덮어씁니다.
shouldUnregister
boolean
입력이 언마운트된 후 등록이 해제되며 defaultValues도 제거됩니다.

참고: 이 속성은 입력이 언마운트/리마운트 및 재정렬된 후 unregister 함수가 호출되므로 useFieldArray와 함께 사용할 때 피해야 합니다.
deps
string | string[]
유효성 검사는 종속 입력에 대해 트리거 됩니다. 이는 trigger가 아닌 register api 에만 제한됩니다.
NameDescription
ref
React.Ref
React 엘리먼트 ref
required
string |
{
  value: boolean,
  message: string
}
폼을 제출하기 전에 해당 입력 필드에 값이 있어야 함을 나타냅니다.

참고: 이 구성은 필수 입력 유효성 검사를 위한 웹 제한 API와 일치합니다. 객체나 배열 유형의 입력인 경우 validate 함수를 대신 사용하세요.
maxLength
{
  value: number,
  message: string
}
이 입력에서 허용할 값의 최대 길이.
minLength
{
  value: number,
  message: string
}
이 입력에서 허용할 값의 최소 길이.
max
{
  value: number,
  message: string
}
이 입력에서 허용할 최대값.
min
{
  value: number,
  message: string
}
이 입력에서 허용할 최소값.
pattern
{
  value: RegExp,
  message: string
}
입력에 대한 정규식 패턴.

참고: /g 플래그를 가진 RegExp 객체는 일치가 발생한 마지막 인덱스를 추적합니다.
validate
Function |
Record<string, Function>
Validate 함수는 required 속성에 포함된 다른 유효성 검사 규칙에 의존하지 않고 독립적으로 실행됩니다.

참고: 다른 규칙들은 주로 문자열, 문자열 배열(string[]), 숫자 및 boolean 데이터 타입에 적용되기 때문에 객체 또는 배열 입력 데이터의 경우 유효성 검사에 validate 함수를 사용하는 것이 권장됩니다.
valueAsNumber
boolean
보통 숫자를 반환합니다. 문제가 발생하면 NaN 이 반환됩니다.
  • valueAs 프로세스는 유효성 검사 전에 발생합니다.
  • 숫자 입력 필드에만 적용되며, 데이더 조작 없이 동작합니다.
  • defaultValue나 defaultValues는 변환되지 않습니다.
valueAsDate
boolean
보통 Date객체를 반환합니다. 문제가 발생하면 Invalid Date가 반환됩니다.
  • valueAs 프로세스는 유효성 검사 전에 발생합니다.
  • 입력 필드에만 적용됩니다.
  • defaultValue나 defaultValues는 변환되지 않습니다.
setValueAs
<T>(value: any) => T
함수를 실행하여 입력값을 반환합니다.
  • valueAs 프로세스는 유효성 검사 전에 발생합니다. 또한, valueAsNumber나 valueAsDate가 true인 경우 setValueAs는 무시됩니다.
  • 텍스트 입력 필드에만 적용됩니다.
  • defaultValue나 defaultValues는 변환되지 않습니다.
disabled
boolean = false
disabled를 true로 설정하면 입력 값이 undefined가 되며 입력 컨트롤이 비활성화됩니다.
  • disabled 속성은 내장된 유효성 검사 규칙도 제외합니다.
  • 스키마 유효성 검사를 위해, 입력 또는 컨텍스트 객체에서 반환된 undefined 값을 활용할 수 있습니다.
onChange
(e: SyntheticEvent) => void
변경 이벤트에서 호출될 onChange 함수.
onBlur
(e: SyntheticEvent) => void
블러(blur) 이벤트에서 호출될 onBlur 함수.
value
unknown
등록된(registered) 입력의 값을 설정합니다. 이 속성은 useEffect 내부에서 사용하거나 한 번만 호출해야 하며, 재실행할 때마다 입력 값을 업데이트하거나 덮어씁니다.
shouldUnregister
boolean
입력이 언마운트된 후 등록이 해제되며 defaultValues도 제거됩니다.

참고: 이 속성은 입력이 언마운트/리마운트 및 재정렬된 후 unregister 함수가 호출되므로 useFieldArray와 함께 사용할 때 피해야 합니다.
deps
string | string[]
유효성 검사는 종속 입력에 대해 트리거 됩니다. 이는 trigger가 아닌 register api 에만 제한됩니다.
RULES

  • 이름은 필수이며 고유해야 합니다(기본 라디오 및 체크박스 제외). 입력 이름은 점과 대괄호 구문을 모두 지원하므로 중첩된 폼 필드를 쉽게 만들 수 있습니다.

  • 이름은 은 숫자로 시작하거나 키 이름으로 숫자를 사용할 수 없습니다. 특수 문자의 사용도 피해야 합니다.

  • TypeScript 사용 시 일관성을 위해 점 구문만을 사용하고 있으므로, 배열 폼 값에는 대괄호 [] 를 사용할 수 없습니다.

    register('test.0.firstName'); // ✅
    register('test[0]firstName'); // ❌
  • 비활성화된 입력은 undefined 폼 값을 결과로 제공합니다. 사용자가 입력을 업데이트하지 못하도록 하려면 readOnly를 사용하거나 전체 fieldset을 비활성화할 수 있습니다. 다음은 예제입니다.
  • 필드 배열을 생성하려면 입력 이름 뒤에 점과 숫자를 붙여야 합니다. 예: test.0.data
  • 렌더링할 때마다 이름을 변경하면 새로운 입력이 등록(registered)됩니다. 따라서 각 등록된(registered) 입력에 대해 고정된 이름을 사용하는 것이 좋습니다.
  • 언마운트에 따라 입력 값과 참조는 더 이상 제거되지 않습니다. 해당 값과 참조를 제거하려면 unregister를 호출할 수 있습니다.

  • 개별 register 옵션은 undefined나 {}로 제거할 수 없습니다. 대신 개별 속성을 업데이트할 수 있습니다.

    register('test', { required: true });
    register('test', {}); // ❌
    register('test', undefined); // ❌
    register('test', { required: false });  // ✅
  • 타입 검사와 충돌을 피하기 위해 ref, _f와 같은 키워드는 피해야 합니다.

Examples

Register input or select

CodeSandbox JS
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>
  )
}

Custom async validation

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>
  )
}

Video

Tips

구조 분해 할당

const { onChange, onBlur, name, ref } = register('firstName');
// 지정한 이름에 해당하는 필드 경로에 대해 타입 검사를 포함합니다.


<input
  onChange={onChange} // onChange 이벤트 할당
  onBlur={onBlur} // onBlur 이벤트 할당
  name={name} // name 속성 할당
  ref={ref} // ref 속성 할당
/>
// 위와 같음
<input {...register('firstName')} />

커스텀 Register

useEffect를 사용해 입력 필드를 등록하고 가상 입력(virtual inputs)으로 취급할 수도 있습니다. 제어 컴포넌트를 위해, 이 과정을 대신 처리해주는 커스텀 훅인 useController와 Controller 컴포넌트를 제공합니다.

필드를 수동으로 등록(register)한다면, setValue를 사용하여 입력 값을 직접 업데이트해야 합니다.

register('firstName', { required: true, min: 8 });


<TextInput onTextChange={(value) => setValue('lastChange', value))} />

innerRef, inputRef로 어떻게 작업할까?

커스텀 입력 컴포넌트가 ref를 올바르게 노출하지 않을 때는, 아래와 같은 방식으로 동작하도록 만들 수 있습니다.

// 동작하지 않음. ref가 할당되지 않았기 때문
<TextInput {...register('test')} />


const firstName = register('firstName', { required: true })
<TextInput
  name={firstName.name}
  onChange={firstName.onChange}
  onBlur={firstName.onBlur}
  inputRef={firstName.ref} // innerRef와 같은 다른 ref 이름에도 동일하게 구현할 수 있습니다.
/>

지원해 주셔서 감사합니다

프로젝트에서 React Hook Form이 유용하다고 생각하신다면, 스타를 눌러 지원해 주시길 부탁드립니다.