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.
<input type="text" value={name} onChange={(e) => setName(e.target.value)} /> <input type="text" defaultValue="Ada" name="name" />
Try it
Because React decides the displayed value, the handler can transform or reject what the user typed. Try typing lower-case letters.
FormData reads every named field once, on submit, and every value is a string. The Reset button restores the defaultValues.
Syntax
<input type="text" name="q" value={value} onChange={handler} />
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):
valuewithoutonChangeorreadOnlywarns that the field will be read-only.- Giving both
valueanddefaultValuewarns; pick one. value={null}warns; use''to clear a field, orundefinedfor an uncontrolled one.- Switching from
undefinedto a real value warns that an uncontrolled input became controlled (and the reverse). Start state as'', notundefined.
Usage notes
- State holds strings. Even for
type="number",event.target.valueis 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.
onChangeis React's input event. It runs on each keystroke. For the browser's commit-on-blur behavior, useonBlurand read the value there.- Use
readOnly, notdisabled, when a user should still be able to focus and copy the text. Disabled fields are excluded fromFormData. - Resetting uncontrolled inputs: give the input or its form a new
keyto remount it with the default value, or callform.reset(). - Labels: wrap the input in a
<label>or connect them withhtmlForandid(useuseIdfor 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 indefaultValueof fields you render to other users. - Checkbox and file inputs follow different rules; see their pages.