React Reference ยท Built-in DOM Components
The input type checkbox in React
Reference for React checkboxes: controlled with checked and onChange, uncontrolled with defaultChecked, groups in state, the indeterminate state and form values.
A checkbox is an <input type="checkbox">. In React its state lives in the checked prop, not in value. value is the string submitted with a form when the box is ticked; checked says whether it is ticked right now.
Like other inputs, a checkbox is controlled when you pass checked together with an onChange handler, and uncontrolled when you pass defaultChecked (or nothing) and let the browser keep the state. In the handler, read event.target.checked, a boolean, not event.target.value.
<input type="checkbox" checked={accepted} onChange={(e) => setAccepted(e.target.checked)} />
Try it
Each box reads its state from the array, so "select all", "clear" and a count are one line each.
indeterminate is a DOM property with no HTML attribute and no React prop, so it is set through a ref. It is only a visual state: checked is still true or false.
Syntax
<input type="checkbox" name="agree" value="yes" checked={bool} onChange={handler} /> <input type="checkbox" name="agree" defaultChecked />
| Prop | Description |
|---|---|
checked |
Boolean. Makes the checkbox controlled. |
defaultChecked |
Initial state of an uncontrolled checkbox. |
onChange |
Handler for each toggle. event.target.checked is the new state. |
value |
String sent with the form when ticked. Default is "on". It never changes when the user clicks. |
name |
Key in FormData. A group of checkboxes with the same name produces repeated entries; read them with getAll. |
disabled, required, readOnly |
required makes the browser demand a tick on submit. readOnly has no effect on checkboxes; use disabled or a controlled box that ignores the change. |
ref |
The HTMLInputElement, needed for indeterminate. |
Returns: a React element with no children.
Warnings: checked without onChange (or readOnly) logs a warning and renders a read-only box. Passing both checked and defaultChecked also warns.
Usage notes
- Use
checked, notvalue, to control a checkbox. Mixing them up is the most common bug:value={true}does nothing useful. - Unticked boxes send nothing.
FormDataleaves out a checkbox that is not ticked, so "missing" meansfalse. If the server needs an explicit value, add a hidden input with the samenamebefore the checkbox. - Groups are arrays or sets. Keep a list of chosen values in state and update it immutably, as in the first example.
- Clicking a label toggles the box. Wrap the input in the label or connect them with
htmlForandid, which also enlarges the click area. - Toggle switches are checkboxes with
role="switch"and styling. KeepcheckedandonChange, and addaria-checkedonly if you replace the native input. - Reset by key. To restore an uncontrolled box to
defaultChecked, remount it with a newkey, or reset its form. - Radio buttons use
checkedthe same way but belong in a group with one sharedname;onChangefires only for the one being selected. - Testing: simulate a click, not
checked = true, so that React sees the event.