How to Add a Toggle Button to React

Before installing the Toggle, confirm your React project has the two things Drivn assumes: Tailwind CSS v4 processing your styles and a @/ path alias pointing at your source directory — the component ships as a .tsx file, so TypeScript is part of the stack. If you scaffolded with create-next-app, npm create vite, or npx drivn@latest create, both are already wired; the installation page lists the minimal config for a custom setup. The Toggle has no runtime UI dependency of its own — no Radix, no cva — so nothing new gets version-locked into your bundle. Its only peer import is a lucide-react icon for the toggle's label, which most projects already have. And because the toggle holds interactive state through React.useState, its source carries a 'use client' directive — render it inside a client boundary, not directly in a framework's server-rendered tree.

Run the CLI from your project root to add the Toggle source. The command writes a single toggle.tsx under your UI directory; there is no runtime Drivn package to version-lock, and the CLI docs cover the flags for targeting a custom path or adding several components in one run. After install the file is yours — a future Drivn release will not overwrite your edits — and the whole component, from the styles object through the Toggle.Group context, is a short file you can read top to bottom. If you also want an icon for the label, lucide-react is the only peer import. Commit the file for a clean baseline before wiring it in.

Start with one standalone toggle. Import Toggle and render it with an icon and a label as children — the base styles apply a gap-2 flex layout so they sit side by side. Left uncontrolled, the toggle owns its state: pass defaultPressed to set the starting value and it flips on each click, updating aria-pressed for assistive tech and a data-state attribute of on or off for the styling. To drive it from your own state instead, pass a pressed prop and an onChange callback — the controlled pattern you want when the pressed value lives in a store or a parent. This is the shape for a single boolean control that should read as a button rather than a checkbox: a Bold button, a Mute toggle, a Pin control. See the Toggle examples for the controlled and uncontrolled variants side by side.

To let several toggles be active at once — the bold, italic, underline toolbar — wrap them in Toggle.Group with type="multiple". Each child takes a value, and the group tracks the active set as a string array through React context, so there is no shared useState to thread and no prop-drilling. Give the group a defaultValue array for an uncontrolled toolbar, or pass value with onValueChange to control it. Each toggle reads whether its value is in the active array and flips its data-state to match, so several can show the pressed styling at the same time. The same Toggle component works standalone or in a group — it detects the context at render time — so you reuse it unchanged. Pair the group with a Button for one-shot actions like "Clear formatting" that fire rather than toggle.

When only one toggle can be active — text alignment, a view mode — set type="single" on the group. The value becomes a single string, selecting one clears the rest like a radio group, and 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 behaviour is otherwise identical, which suits a sidebar tool rail. To disable a whole group, set disabled on Toggle.Group — it passes down through context, and each child falls back to it unless it sets its own disabled. Switching a horizontal multiple-select toolbar to a vertical single-select list is a couple of attribute changes, not a rewrite, because every option is a plain prop on the group.

Every visual difference between a pressed and an idle toggle comes from 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 — 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 object, and both props are typed against it so they autocomplete with no magic strings. To restyle the pressed state — a brand color instead of the muted fill — you edit the one data-[state=on]: line rather than threading a config prop, because Drivn writes the source into your repo instead of shipping a locked package. The block below is copied verbatim from toggle.ts. See theming to align the tokens it references with your app.