Skip to content
Tutorials Center
My learning

Topics

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.

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

Try it

Controlled fields
Uncontrolled fields read on submit

Syntax

JSX
<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:

  • value without onChange or readOnly: 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 or undefined for uncontrolled.
  • Switching from undefined to a defined value (or the reverse) logs a warning that a component changed an input between uncontrolled and controlled.
  • Passing both value and defaultValue logs 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 with slice.
  • Initialize state with '', not undefined or null, to avoid the uncontrolled-to-controlled warning. For numbers, store the string while typing and convert when you use it.
  • defaultValue is read once. To load different starting data, give the field (or the form) a new key, which remounts it with the new default.
  • Reset behavior. A <button type="reset"> restores uncontrolled fields to their defaultValue. Controlled fields are reset by clearing the state that feeds them. React 19 also resets uncontrolled fields after a successful form action.
  • <textarea> uses value and defaultValue, not children, unlike plain HTML. <select> uses value on the <select> itself instead of selected on <option>.
  • File inputs are always uncontrolled. Their value is 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.
  • onChange in React fires on each input event, not only on blur as in plain HTML. See onChange.
  • Do not mix. Use checked and defaultChecked for checkboxes and radio buttons instead.