React Checkbox Component Examples

The minimum Drivn Checkbox is one tag with a label prop. The component renders an <input type="checkbox"> hidden via sr-only, a styled <span> for the visual box, and a <span> for the label text — all inside a single <label> element. Click anywhere on the row (box or text) toggles the checkbox because the native <label> element forwards clicks to the input automatically.

The label text uses text-sm text-foreground select-none per the Checkbox source — small body type, foreground color, and select-none so double-click on the label does not select text accidentally. For longer descriptions or paragraph-style copy next to a checkbox, render the text outside the component and use aria-describedby to associate it. For a one-line label, the prop is enough.

Pass checked and onChange to control the checkbox from parent state. The Drivn Checkbox source detects the controlled mode via const isControlled = checked !== undefined and skips the internal useState update, forwarding the change event to your handler unchanged. Read event.target.checked for the boolean — the onChange signature is the standard ChangeEventHandler<HTMLInputElement>, the same one you use on every other form input.

Use controlled mode when the checkbox state needs to drive other UI — toggling a downstream form section, filtering a list, enabling a submit button. For pure toggle state with no side effects, defaultChecked keeps the component uncontrolled and skips the re-render of the parent on every toggle.

Pass defaultChecked for an uncontrolled checkbox that starts in the checked state. The Drivn Checkbox stores the state internally via useState(defaultChecked ?? false) and updates it on every change without notifying the parent unless you pass an onChange. This is the right shape for newsletter opt-ins, "remember me" toggles, and any preference that lives entirely inside a form payload.

Uncontrolled checkboxes pair well with native form submission — the input's name attribute serializes the boolean value into FormData when the user submits, with no React state ferrying needed. For react-hook-form, defaultChecked is overridden by register() because the form library takes ownership of the input via refs.

Pass disabled to lock the checkbox into its current state. The Checkbox source applies opacity-50 cursor-default to the wrapping <label> via cn(styles.base, disabled && 'opacity-50 cursor-default', className) and forwards the disabled attribute to the native <input> so click events are blocked at the DOM level. Combine with checked or defaultChecked to render a locked-on or locked-off state.

Disabled checkboxes are common for cannot-change settings — already-accepted terms, plan limits, organization-wide policies. Pair them with a tooltip or explanatory text via aria-describedby so screen readers explain why the field is locked rather than just announcing "disabled".

For multi-select fields — notification preferences, feature flags, category filters — render a stack of Checkboxes inside a <div className="flex flex-col gap-3">. Each checkbox is independent, with its own name and checked state. There is no CheckboxGroup wrapper in Drivn because the native HTML pattern already supports independent checkboxes inside a <form> without any grouping component.

For a "select all" toggle that controls a group, lift the state into the parent — track an array of selected values, derive allChecked from selected.length === options.length, and toggle the array on each child change. The pattern is twenty lines of plain React without any new component.

Drop a Drivn Checkbox inside a <form> with name and value attributes and the field serializes natively on submit — no FormData wiring, no controlled-state ferrying. The native <input type="checkbox"> element participates in form submission directly because the visible row is built around a real input, not a button-with-aria-checked. Set required to enforce the value via HTML5 validation, and the browser will block submit until the user checks the box.

For react-hook-form, register() works without a <Controller> wrapper. Spread the register return into the Checkbox — <Checkbox {...register("agree", { required: true })} label="I agree" /> — and validation, error state, and submit serialization all work via the native input. The same pattern works for Formik, Conform, or any form library that targets standard HTML inputs.