Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Built-in DOM Components

The input element in React

Reference for the React input element: controlled inputs with value and onChange, uncontrolled inputs with defaultValue, warnings, types and common mistakes.

<input> is the most flexible form control: its type turns it into a text box, number field, date picker, slider, password field, checkbox, radio button, file chooser and more. React adds one idea on top of the HTML element: an input is either controlled or uncontrolled.

A controlled input has a value prop. React shows exactly that value, and the field only changes when your onChange handler updates state and the component renders again. An uncontrolled input has no value; the browser keeps the text, you give a starting point with defaultValue, and you read the result with a ref or from the form's FormData. Pick one for the lifetime of the element.

JSX
<input type="text" value={name} onChange={(e) => setName(e.target.value)} />
<input type="text" defaultValue="Ada" name="name" />

Try it

A controlled input

Because React decides the displayed value, the handler can transform or reject what the user typed. Try typing lower-case letters.

An uncontrolled form

FormData reads every named field once, on submit, and every value is a string. The Reset button restores the defaultValues.

Syntax

JSX
<input type="text" name="q" value={value} onChange={handler} />
TypeScript
type InputProps = React.InputHTMLAttributes<HTMLInputElement>;
Prop Description
type The kind of control (text, number, email, password, range, date, search, checkbox, radio, file, and so on). Default text.
value Makes the input controlled. A string or number; do not pass null.
defaultValue Initial value of an uncontrolled input. Changing it later does nothing.
onChange Fires on every edit, not only on blur (unlike the DOM change event). Read event.target.value.
checked, defaultChecked Same pattern for checkboxes and radios; see input type checkbox.
name, form, required, disabled, readOnly, placeholder, min, max, step, pattern, maxLength, autoComplete, inputMode Passed to the DOM element. readOnly and maxLength use camelCase.
ref The HTMLInputElement, for focus(), select() or reading an uncontrolled value.

Returns: a React element. It cannot have children.

Errors and warnings (development builds):

  • value without onChange or readOnly warns that the field will be read-only.
  • Giving both value and defaultValue warns; pick one.
  • value={null} warns; use '' to clear a field, or undefined for an uncontrolled one.
  • Switching from undefined to a real value warns that an uncontrolled input became controlled (and the reverse). Start state as '', not undefined.

Usage notes

  • State holds strings. Even for type="number", event.target.value is a string; convert it yourself, and allow the empty string while the user is typing.
  • Keep one source of truth. Do not mirror a controlled value into a second state variable; derive what you need during render.
  • onChange is React's input event. It runs on each keystroke. For the browser's commit-on-blur behavior, use onBlur and read the value there.
  • Use readOnly, not disabled, when a user should still be able to focus and copy the text. Disabled fields are excluded from FormData.
  • Resetting uncontrolled inputs: give the input or its form a new key to remount it with the default value, or call form.reset().
  • Labels: wrap the input in a <label> or connect them with htmlFor and id (use useId for the id).
  • Performance: a controlled input re-renders its component on every keystroke. This is cheap for a form, but move state down or to the uncontrolled style when a huge tree re-renders with it.
  • Security: type="password" only hides characters. Never put secrets in defaultValue of fields you render to other users.
  • Checkbox and file inputs follow different rules; see their pages.