[react-dom 번역] <input>

출처: https://react.dev/reference/react-dom/components/input

Reference

`<input>`

내장 브라우저 <input> 컴포넌트는 다양한 종류의 폼 입력을 렌더링할 수 있습니다.

<input name="myInput" />

아래에서 더 많은 예시를 확인할 수 있습니다.

Props

<input>은 모든 공통 엘리먼트 props를 지원합니다.

formAction: 문자열 또는 함수. type="submit" 및 type="image"에서 부모 <form action>을 오버라이드합니다. URL을 전달하면 표준 HTML form처럼 동작하고, 함수를 전달하면 해당 함수가 폼 제출을 처리합니다. 자세한 내용은 <form action> 참고.

입력을 제어형으로 만들려면 다음 props 중 하나를 전달하세요:

checked: boolean. 체크박스나 라디오 버튼에서 선택 여부를 제어합니다.
value: string. 텍스트 입력에서 텍스트를 제어합니다. (라디오 버튼에서는 폼 데이터 지정)

이 중 하나를 전달할 때는 반드시 값을 업데이트하는 onChange 핸들러도 함께 전달해야 합니다.

비제어 입력에만 관련된 props:

defaultChecked: boolean. 체크박스/라디오 버튼의 초기값 지정
defaultValue: string. 텍스트 입력의 초기값 지정

제어형/비제어형 모두에 관련된 props:

accept: string. 파일 입력(type="file")에서 허용할 파일 타입 지정
alt: string. 이미지 입력(type="image")의 대체 텍스트
capture: string. 파일 입력(type="file")에서 캡처할 미디어 종류 지정
autoComplete: string. 자동완성 동작 지정
autoFocus: boolean. true면 마운트 시 자동 포커스
dirname: string. 입력 방향성 필드명 지정
disabled: boolean. true면 비활성화 및 흐리게 표시
children: <input>은 children을 허용하지 않습니다.
form: string. 이 input이 속한 <form>의 id 지정(생략 시 가장 가까운 부모 form)
formAction, formEnctype, formMethod, formNoValidate, formTarget: 각각 부모 form의 해당 속성을 오버라이드
height, width: 이미지 입력(type="image")의 높이/너비
list: string. 자동완성 옵션을 가진 <datalist>의 id
max, min: 숫자/날짜 입력의 최대/최소값
maxLength, minLength: 텍스트 입력의 최대/최소 길이
multiple: boolean. 파일/이메일 입력에서 다중 값 허용
name: string. 폼 제출 시 함께 전송되는 이름
onChange: 이벤트 핸들러. 제어형 입력에서 필수. 값이 변경될 때마다 즉시 호출(키 입력마다 동작)
onInput: 이벤트 핸들러. 값이 변경될 때마다 호출. (React에서는 onChange 사용 권장)
onInvalid: 유효성 검사 실패 시 호출. React의 onInvalid는 버블링됨
onSelect: 입력 내 선택 영역이 변경될 때 호출
pattern: string. 값이 일치해야 하는 정규식 패턴
placeholder: string. 값이 비어 있을 때 흐리게 표시되는 안내문구
readOnly: boolean. true면 사용자가 수정 불가
required: boolean. true면 값이 반드시 필요
size: number. 입력의 표시 크기(단위는 컨트롤에 따라 다름)
src: string. 이미지 입력의 소스
step: 양수 또는 'any'. 유효값 간격 지정
type: string. 입력 타입 지정

Caveats(주의사항)

<input>은 children을 허용하지 않습니다.
제어형 입력에서 value/checked를 전달할 때는 반드시 onChange도 함께 전달해야 합니다.
value는 항상 string이어야 하며, undefined/null을 전달하면 안 됩니다. (초기값이 없으면 빈 문자열 전달)
checked는 항상 boolean이어야 합니다.

사용법

다양한 타입의 입력 표시

<input type="text" />
<input type="number" />
<input type="checkbox" />
<input type="radio" />
<input type="file" />
<input type="image" src="/logo.png" alt="로고" />

입력에 label 제공

<label htmlFor="username">사용자명</label>
<input id="username" name="username" />

입력의 초기값 지정

<input defaultValue="기본값" />
<input type="checkbox" defaultChecked={true} />

폼 제출 시 입력값 읽기

function MyForm() {
  function handleSubmit(e) {
    e.preventDefault();
    const formData = new FormData(e.target);
    alert(formData.get('myInput'));
  }
  return (
    <form onSubmit={handleSubmit}>
      <input name="myInput" />
      <button type="submit">제출</button>
    </form>
  );
}

state로 입력 제어 (제어형 input)

import { useState } from 'react';

function Example() {
  const [value, setValue] = useState('');
  return (
    <input value={value} onChange={e => setValue(e.target.value)} />
  );
}

체크박스/라디오 버튼 제어

import { useState } from 'react';

function Example() {
  const [checked, setChecked] = useState(false);
  return (
    <input type="checkbox" checked={checked} onChange={e => setChecked(e.target.checked)} />
  );
}

입력 최적화 (re-render 최소화)

입력값을 state로 제어할 때, 상위 컴포넌트가 큰 트리를 렌더링하면 성능 저하가 발생할 수 있습니다. 이럴 땐 입력 state를 별도 컴포넌트로 분리하거나, useDeferredValue 등으로 최적화할 수 있습니다.

트러블슈팅

텍스트 입력이 입력 시 갱신되지 않음

value를 전달했지만 onChange를 전달하지 않으면 입력이 동작하지 않습니다.
초기값만 지정하려면 defaultValue를 사용하세요.
제어형 입력에는 반드시 onChange를 지정하세요.
읽기 전용으로 만들려면 readOnly를 추가하세요.

체크박스가 클릭해도 갱신되지 않음

checked를 전달했지만 onChange를 전달하지 않으면 입력이 동작하지 않습니다.
초기값만 지정하려면 defaultChecked를 사용하세요.
제어형 입력에는 반드시 onChange를 지정하세요.
읽기 전용으로 만들려면 readOnly를 추가하세요.
체크박스의 값은 e.target.checked로 읽어야 합니다.

입력 커서가 매 입력마다 앞으로 이동함

onChange에서 state를 비동기로 업데이트하거나, e.target.value가 아닌 다른 값으로 업데이트하면 커서가 앞으로 이동할 수 있습니다.
항상 onChange에서 e.target.value(또는 checked)를 동기적으로 state에 반영하세요.

"A component is changing an uncontrolled input to be controlled" 오류

value는 항상 string이어야 하며, undefined/null이 아닌 빈 문자열('')을 전달해야 합니다.
checked는 항상 boolean이어야 합니다.