Next.js Toggle Component with Drivn

Drivn installs through a small CLI that writes the component source directly into your repository — there is no runtime UI package to version-lock, and no Radix primitive underneath. From the root of your Next.js 16 project run npx drivn add toggle. The command writes a single toggle.tsx under your UI directory; the CLI reference documents every flag, including targeting a custom path or adding several components at once. The only peer import is a lucide-react icon for the toggle's label, which most Drivn projects already have installed. After install the file is yours — a future Drivn release will not overwrite your edits — and the whole component, from the styles object to the Toggle.Group context, is a short file you can read top to bottom. Commit it for a clean baseline before wiring it in, then see the installation guide if you are adding Drivn to an existing project for the first time.

With the source installed, the smallest useful toggle is a single controlled button. Because a toggle tracks whether it is pressed, the component that renders it holds that state — mark the wrapper 'use client', keep the value in React.useState(false), and pass pressed and onChange. Drivn's Toggle sets aria-pressed from that value and mirrors it to a data-state of on or off, so screen readers announce the state and your styles can target it. Pass a lucide-react icon and a label as children; the base styles apply a gap-2 flex layout so the icon and text sit side by side. A Server Component page cannot own this state, which is why the toggle lives in a client wrapper you then import anywhere. Leave pressed off and pass defaultPressed instead for an uncontrolled toggle that manages its own state. See the Toggle examples for more variants.

For a toolbar where several options can be active at once, wrap your toggles in Toggle.Group with type="multiple". Each child Toggle takes a value, and the group tracks the active set through React context — no prop-drilling and no shared useState in your component. Give the group a defaultValue array for an uncontrolled toolbar, or pass value and onValueChange to control it. Inside the group each toggle reads whether its value is in the active array and flips its data-state accordingly, so a pressed Bold and Italic both show the active styling at the same time. This is the classic rich-text toolbar pattern — bold, italic, underline, strikethrough — and because the group is context-driven you can drop new toggles in without rewiring state. The whole group is still a client component, so mount it inside a 'use client' wrapper. Pair it with a Button for actions that fire rather than toggle.

When only one option can be active — text alignment, a view mode — set type="single" on the group. Selecting a toggle now clears the others, exactly like a radio group, and the group's value is a single string rather than an array. The deselect behaviour is built in: in single mode, clicking the already-active toggle clears it back to an empty string, so the control can be turned off entirely. Add orientation="vertical" to stack the toggles in a column instead of a row — the group applies a flex-col class and the toggles lay out top to bottom, which suits a sidebar of view options. Both are plain attributes on Toggle.Group, so switching a horizontal multiple-select toolbar to a vertical single-select list is two attribute changes, not a rewrite. The alignment example shows the single-select pattern with left, center, right, and justify.

Every visual difference between a pressed and an idle toggle is driven by one attribute: data-state. Drivn sets it to on or off on the button, and the styles object targets it with Tailwind's data-[state=on]: variant — so a pressed toggle gets bg-muted and text-foreground while an idle one stays transparent with muted text. There are two variants, default and outline, and three sizes, sm, md, and lg, all held in the same styles object you own after install. To restyle the pressed state — say a brand color instead of the muted background — you edit the one data-[state=on]: line rather than threading a config prop. The block below is copied verbatim from toggle.ts; because you own the file, this is the whole surface you customize, with no variant map hidden behind a package boundary. See theming to align the tokens it references with the rest of your app.