Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Props and Attributes

React checked and defaultChecked props

Learn the difference between checked and defaultChecked in React: controlled and uncontrolled checkboxes and radio buttons, with the warnings and fixes.

Checkboxes and radio buttons have a boolean state of their own. React gives you two props to deal with it. checked makes the input controlled: React decides whether the box is ticked, and your onChange handler must update state. defaultChecked makes it uncontrolled: it only sets the initial state, and after that the browser owns the box.

Pick one per input. A controlled checkbox is the right default when other parts of the screen depend on the answer. An uncontrolled one is fine for a plain form that you read once on submit.

JSX
<input type="checkbox" checked={isOn} onChange={(e) => setIsOn(e.target.checked)} />
<input type="checkbox" defaultChecked />

Try it

Controlled and uncontrolled checkboxes

For a group of radio buttons, compare each option against one piece of state and give the group a shared name.

A controlled radio group

Syntax

JSX
<input type="checkbox" checked={boolean} onChange={handler} />
<input type="radio" checked={boolean} onChange={handler} />
<input type="checkbox" defaultChecked={boolean} />
Name Description
checked Boolean. Whether the checkbox or radio button is ticked. Requires onChange (or readOnly).
defaultChecked Boolean. The initial state of an uncontrolled input. Changing it later has no effect.
onChange Called when the user toggles the input. Read the new state from event.target.checked.

Edge cases and warnings:

  • checked without onChange (and without readOnly) logs a warning in development, and the box cannot be toggled.
  • Passing both checked and defaultChecked logs a warning; React uses checked.
  • Switching between checked={undefined} and a real boolean logs "changing an uncontrolled input to be controlled", because the input changes kind.

Usage notes

  • Use e.target.checked, not e.target.value. The value of a checkbox is a fixed string (default "on"), not its state.
  • Never initialise state with undefined. Write useState(false), so the input is controlled from the first render.
  • Radio groups: the browser un-ticks siblings that share a name, but React still trusts your state. Compute checked from one source of truth, as above.
  • indeterminate is not a prop. Set ref.current.indeterminate = true in an effect or ref callback.
  • Resetting an uncontrolled box: change its key to remount it with defaultChecked again.
  • Read-only display: pass checked with readOnly (or disabled) to show a state that the user cannot change.