Skip to content
Tutorials Center
My learning

Topics

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.

JSX
<input
  type="checkbox"
  checked={accepted}
  onChange={(e) => setAccepted(e.target.checked)}
/>

Try it

A controlled checkbox and a group

Each box reads its state from the array, so "select all", "clear" and a count are one line each.

Select all with indeterminate

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

JSX
<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, not value, to control a checkbox. Mixing them up is the most common bug: value={true} does nothing useful.
  • Unticked boxes send nothing. FormData leaves out a checkbox that is not ticked, so "missing" means false. If the server needs an explicit value, add a hidden input with the same name before 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 htmlFor and id, which also enlarges the click area.
  • Toggle switches are checkboxes with role="switch" and styling. Keep checked and onChange, and add aria-checked only if you replace the native input.
  • Reset by key. To restore an uncontrolled box to defaultChecked, remount it with a new key, or reset its form.
  • Radio buttons use checked the same way but belong in a group with one shared name; onChange fires only for the one being selected.
  • Testing: simulate a click, not checked = true, so that React sees the event.