Next.js Checkbox — Forms, Server Actions & FormData

Drivn ships no runtime package — the CLI copies the component source into your repository and leaves. From the root of your Next.js 16 project run npx drivn add checkbox. The CLI asks once where components live, defaulting to src/components/ui/, and writes checkbox.tsx there. The file imports React, the local cn class-merge helper, and a single icon — Check from lucide-react for the tick mark — so confirm that package is present. Everything else is Tailwind classes collected in a styles object at the top of the file. The CLI reference covers custom directories and batch installs, and the installation guide lists project prerequisites. Once the file lands it is yours to edit; Drivn releases never overwrite it.

Open checkbox.tsx and the first line is 'use client'. The reason is the uncontrolled path: the component initializes const [internal, setInternal] = React.useState(defaultChecked ?? false) and toggles it on change when no checked prop is supplied. State plus an event handler means the file must hydrate on the client, so importing the Checkbox into a Server Component automatically draws the boundary at that import — you do not add 'use client' to your page. This differs from the Button, which has no directive and stays server-rendered. The practical upshot: render the Checkbox wherever you like in the App Router, and Next.js ships exactly the small client bundle the component needs and nothing more.

The native <input type="checkbox"> inside the component is hidden with className="sr-only", which means it is invisible but still part of the form and still posts with the rest of the fields. Give the Checkbox a name and drop it inside a <form action={...}> bound to a Server Action — the box reads its value straight out of FormData with no onChange handler. A checked box sends its value (defaulting to the browser's "on"); an unchecked box is simply absent from the payload, which is the standard HTML convention you read with formData.get('name'). The whole form stays server-rendered except for the Checkbox itself, so the only client JavaScript is the few lines the component needs to toggle its own visual state.

When the UI has to react to the checkbox before submit — enabling a button, revealing a field, syncing two boxes — pass a checked prop and the component switches to controlled mode (isControlled = checked !== undefined). It then mirrors whatever you pass and fires onChange with the native change event, so you read e.target.checked to update your state. This requires a client component, so put the directive at the top of the small leaf file that owns the state, not on the whole page. The Checkbox examples page collects more of these patterns; the Input component pairs with it for fuller forms.

Pass disabled and the component adds opacity-50 cursor-default to the wrapping <label> and sets disabled on the hidden input, so clicks no longer toggle it. Because the styled box is a sibling <span> and the real control is the sr-only input wrapped in a <label>, clicking the label or its text checks the box and screen readers announce a real checkbox role and state — there is no role="checkbox" shim or manual ARIA to maintain. Keyboard focus and the spacebar toggle come for free from the native element. The tick is a Check icon rendered only when isChecked is true, sized w-2.5 h-2.5, sitting inside a w-4 h-4 box that flips to bg-primary border-primary when checked. Re-theme those by editing the color tokens the classes reference.