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.
<input type="checkbox" checked={isOn} onChange={(e) => setIsOn(e.target.checked)} /> <input type="checkbox" defaultChecked />
Try it
For a group of radio buttons, compare each option against one piece of state and give the group a shared name.
Syntax
<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:
checkedwithoutonChange(and withoutreadOnly) logs a warning in development, and the box cannot be toggled.- Passing both
checkedanddefaultCheckedlogs a warning; React useschecked. - 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, note.target.value. Thevalueof a checkbox is a fixed string (default"on"), not its state. - Never initialise state with
undefined. WriteuseState(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. Computecheckedfrom one source of truth, as above. indeterminateis not a prop. Setref.current.indeterminate = truein an effect or ref callback.- Resetting an uncontrolled box: change its
keyto remount it withdefaultCheckedagain. - Read-only display: pass
checkedwithreadOnly(ordisabled) to show a state that the user cannot change.