<input>·续
label { display: block; }
input { margin: 5px; }
Reading the input values when submitting a form
Add a <form> around your inputs with a <button type="submit"> inside. It will call your <form onSubmit> event handler. By default, the browser will send the form data to the current URL and refresh the page. You can override that behavior by calling e.preventDefault(). Read the form data with new FormData(e.target).
export default function MyForm() {
function handleSubmit(e) {
// Prevent the browser from reloading the page
e.preventDefault();
// Read the form data
const form = e.target;
const formData = new FormData(form);
// You can pass formData as a fetch body directly:
fetch('/some-api', { method: form.method, body: formData });
// Or you can work with it as a plain object:
const formJson = Object.fromEntries(formData.entries());
console.log(formJson);
}
return (
<form method="post" onSubmit={handleSubmit}>
<label>
Text input: <input name="myInput" defaultValue="Some initial value" />
</label>
<hr />
<label>
Checkbox: <input type="checkbox" name="myCheckbox" defaultChecked={true} />
</label>
<hr />
<p>
Radio buttons:
<label><input type="radio" name="myRadio" value="option1" /> Option 1</label>
<label><input type="radio" name="myRadio" value="option2" defaultChecked={true} /> Option 2</label>
<label><input type="radio" name="myRadio" value="option3" /> Option 3</label>
</p>
<hr />
<button type="reset">Reset form</button>
<button type="submit">Submit form</button>
</form>
);
}
label { display: block; }
input { margin: 5px; }
[!NOTE]
Give a
nameto every<input>, for example<input name="firstName" defaultValue="Taylor" />. Thenameyou specified will be used as a key in the form data, for example{ firstName: "Taylor" }.[!WARNING]
By default, a
<button>inside a<form>without atypeattribute will submit it. This can be surprising! If you have your own customButtonReact component, consider using<button type="button">instead of<button>(with no type). Then, to be explicit, use<button type="submit">for buttons that are supposed to submit the form.
Controlling an input with a state variable
An input like <input /> is uncontrolled. Even if you pass an initial value like <input defaultValue="Initial text" />, your JSX only specifies the initial value. It does not control what the value should be right now.
To render a controlled input, pass the value prop to it (or checked for checkboxes and radios). React will force the input to always have the value you passed. Usually, you would do this by declaring a state variable:
```js {2,6,7} function Form() { const [firstName, setFirstName] = useState(''); // Declare a state variable... // ... return ( setFirstName(e.target.value)} // ... and update the state variable on any edits! /> ); }
A controlled input makes sense if you needed state anyway--for example, to re-render your UI on every edit:
```js {2,9}
function Form() {
const [firstName, setFirstName] = useState('');
return (
<>
<label>
First name:
<input value={firstName} onChange={e => setFirstName(e.target.value)} />
</label>
{firstName !== '' && <p>Your name is {firstName}.</p>}
...
It's also useful if you want to offer multiple ways to adjust the input state (for example, by clicking a button):
```js {3-4,10-11,14} function Form() { // ... const [age, setAge] = useState(''); const ageAsNumber = Number(age); return ( <>
The `value` you pass to controlled components should not be `undefined` or `null`. If you need the initial value to be empty (such as with the `firstName` field below), initialize your state variable to an empty string (`''`).
```js
import { useState } from 'react';
export default function Form() {
const [firstName, setFirstName] = useState('');
const [age, setAge] = useState('20');
const ageAsNumber = Number(age);
return (
<>
<label>
First name:
<input
value={firstName}
onChange={e => setFirstName(e.target.value)}
/>
</label>
<label>
Age:
<input
value={age}
onChange={e => setAge(e.target.value)}
type="number"
/>
<button onClick={() => setAge(ageAsNumber + 10)}>
Add 10 years
</button>
</label>
{firstName !== '' &&
<p>Your name is {firstName}.</p>
}
{ageAsNumber > 0 &&
<p>Your age is {ageAsNumber}.</p>
}
</>
);
}
label { display: block; }
input { margin: 5px; }
p { font-weight: bold; }
[!WARNING]
If you pass
valuewithoutonChange, it will be impossible to type into the input. When you control an input by passing somevalueto it, you force it to always have the value you passed. So if you pass a state variable as avaluebut forget to update that state variable synchronously during theonChangeevent handler, React will revert the input after every keystroke back to thevaluethat you specified.
Optimizing re-rendering on every keystroke
When you use a controlled input, you set the state on every keystroke. If the component containing your state re-renders a large tree, this can get slow. There's a few ways you can optimize re-rendering performance.
For example, suppose you start with a form that re-renders all page content on every keystroke:
```js {5-8} function App() { const [firstName, setFirstName] = useState(''); return ( <>
Since `<PageContent />` doesn't rely on the input state, you can move the input state into its own component:
```js {4,10-17}
function App() {
return (
<>
<SignupForm />
<PageContent />
</>
);
}
function SignupForm() {
const [firstName, setFirstName] = useState('');
return (
<form>
<input value={firstName} onChange={e => setFirstName(e.target.value)} />
</form>
);
}
This significantly improves performance because now only SignupForm re-renders on every keystroke.
If there is no way to avoid re-rendering (for example, if PageContent depends on the search input's value), useDeferredValue lets you keep the controlled input responsive even in the middle of a large re-render.
Troubleshooting
My text input doesn't update when I type into it
If you render an input with value but no onChange, you will see an error in the console:
// 🔴 Bug: controlled text input with no onChange handler
<input value={something} />
You provided a value prop to a form field without an onChange handler. This will render a read-only field. If the field should be mutable use defaultValue. Otherwise, set either onChange or readOnly.
As the error message suggests, if you only wanted to specify the initial value, pass defaultValue instead:
// ✅ Good: uncontrolled input with an initial value
<input defaultValue={something} />
If you want to control this input with a state variable, specify an onChange handler:
// ✅ Good: controlled input with onChange
<input value={something} onChange={e => setSomething(e.target.value)} />
If the value is intentionally read-only, add a readOnly prop to suppress the error:
// ✅ Good: readonly controlled input without on change
<input value={something} readOnly={true} />
My checkbox doesn't update when I click on it
If you render a checkbox with checked but no onChange, you will see an error in the console:
// 🔴 Bug: controlled checkbox with no onChange handler
<input type="checkbox" checked={something} />
You provided a checked prop to a form field without an onChange handler. This will render a read-only field. If the field should be mutable use defaultChecked. Otherwise, set either onChange or readOnly.
As the error message suggests, if you only wanted to specify the initial value, pass defaultChecked instead:
// ✅ Good: uncontrolled checkbox with an initial value
<input type="checkbox" defaultChecked={something} />
If you want to control this checkbox with a state variable, specify an onChange handler:
// ✅ Good: controlled checkbox with onChange
<input type="checkbox" checked={something} onChange={e => setSomething(e.target.checked)} />
[!WARNING]
You need to read
e.target.checkedrather thane.target.valuefor checkboxes.
If the checkbox is intentionally read-only, add a readOnly prop to suppress the error:
// ✅ Good: readonly controlled input without on change
<input type="checkbox" checked={something} readOnly={true} />
My input caret jumps to the beginning on every keystroke
If you control an input, you must update its state variable to the input's value from the DOM during onChange.
You can't update it to something other than e.target.value (or e.target.checked for checkboxes):
function handleChange(e) {
// 🔴 Bug: updating an input to something other than e.target.value
setFirstName(e.target.value.toUpperCase());
}
You also can't update it asynchronously:
function handleChange(e) {
// 🔴 Bug: updating an input asynchronously
setTimeout(() => {
setFirstName(e.target.value);
}, 100);
}
To fix your code, update it synchronously to e.target.value:
function handleChange(e) {
// ✅ Updating a controlled input to e.target.value synchronously
setFirstName(e.target.value);
}
If this doesn't fix the problem, it's possible that the input gets removed and re-added from the DOM on every keystroke. This can happen if you're accidentally resetting state on every re-render, for example if the input or one of its parents always receives a different key attribute, or if you nest component function definitions (which is not supported and causes the "inner" component to always be considered a different tree).
I'm getting an error: "A component is changing an uncontrolled input to be controlled"
If you provide a value to the component, it must remain a string throughout its lifetime.
You cannot pass value={undefined} first and later pass value="some string" because React won't know whether you want the component to be uncontrolled or controlled. A controlled component should always receive a string value, not null or undefined.
If your value is coming from an API or a state variable, it might be initialized to null or undefined. In that case, either set it to an empty string ('') initially, or pass value={someValue ?? ''} to ensure value is a string.
Similarly, if you pass checked to a checkbox, ensure it's always a boolean.
