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".

Drivn ships no CheckboxGroup, and that is not an omission. Independent checkboxes inside a <form> are already a complete HTML pattern — each input carries its own name, each serializes on its own, and a wrapper component would only re-implement what the browser does for free. Stack them in a <div className="flex flex-col gap-3"> and the group is finished.

Where shared state does earn its keep is a derived selection array: filter facets, notification channels, permission matrices. Hold a string[] in the parent, pass checked={selected.includes(option)} to each Checkbox, and add or remove the value in onChange. That one array also powers a "select all" control — selected.length === options.length gives you the parent checkbox state, and clicking it either fills the array with every option or empties it. For single-select rather than multi-select, reach for Radio Group, which enforces mutual exclusivity through the native name attribute instead of through your state shape.

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.