React Reference ยท Props and Attributes
React value and defaultValue props
Reference for value and defaultValue on React form fields: controlled versus uncontrolled inputs, the read-only warning, null values and switching modes.
Form fields such as <input>, <textarea> and <select> hold their own text in the browser. React gives you two ways to deal with that. With value, React is in charge: the field always shows the value you pass, and you update it in an onChange handler. This is a controlled field. With defaultValue, you only set the starting text; the browser keeps track of changes after that, and you read the result when you need it. This is an uncontrolled field.
Choose controlled when the UI must react to every keystroke (live validation, formatting, enabling a button, mirroring text elsewhere). Choose uncontrolled when you only need the value at submit time and want less code and fewer renders.
<input value={name} onChange={(e) => setName(e.target.value)} /> {/* controlled */} <input defaultValue="Ada" name="name" /> {/* uncontrolled */}
Try it
Syntax
<input value={string} onChange={handler} /> <input defaultValue={string} /> <textarea value={string} onChange={handler} /> <select value={string | string[]} onChange={handler} />
| Name | Description |
|---|---|
value |
The current text. Makes the field controlled. Must be a string (numbers are converted). Needs onChange or readOnly. For <select multiple> pass an array. |
defaultValue |
The initial text of an uncontrolled field. Later changes to this prop do not affect the field. |
onChange |
Called on every edit with an event whose target.value is the new text. |
readOnly |
Allows value without onChange; the user cannot edit the field. |
Returns: a field showing the given text.
Warnings and errors:
valuewithoutonChangeorreadOnly:You provided a value prop to a form field without an onChange handler. This will render a read-only field.value={null}:value prop on input should not be null. Use''for empty orundefinedfor uncontrolled.- Switching from
undefinedto a definedvalue(or the reverse) logs a warning that a component changed an input between uncontrolled and controlled. - Passing both
valueanddefaultValuelogs a warning; pick one.
Usage notes
- A controlled field only shows what state says. If you forget to update state in
onChange, the field looks frozen. You can use this on purpose to reject characters, as the first example does withslice. - Initialize state with
'', notundefinedornull, to avoid the uncontrolled-to-controlled warning. For numbers, store the string while typing and convert when you use it. defaultValueis read once. To load different starting data, give the field (or the form) a newkey, which remounts it with the new default.- Reset behavior. A
<button type="reset">restores uncontrolled fields to theirdefaultValue. Controlled fields are reset by clearing the state that feeds them. React 19 also resets uncontrolled fields after a successful form action. <textarea>usesvalueanddefaultValue, not children, unlike plain HTML.<select>usesvalueon the<select>itself instead ofselectedon<option>.- File inputs are always uncontrolled. Their
valueis read-only for security. See<input type="file">. - Performance. Controlled fields re-render on every keystroke. This is usually fine; for huge forms, split fields into small components or use uncontrolled fields with
FormData. onChangein React fires on each input event, not only on blur as in plain HTML. SeeonChange.- Do not mix. Use
checkedanddefaultCheckedfor checkboxes and radio buttons instead.