# Toggle lever

An everyday on/off switch, as a bat-handle toggle on a small plate. The lever swings through its bushing toward the side that's on and settles with a little spring; a lamp at the end of the plate lights. For settings rows. (For banks of config bits use DIP switches; for dangerous actions, the guarded switch.)

- Category: Essentials
- Docs: https://bevel-ui.vercel.app/components/toggle-lever
- Import from: `@/components/ui/toggle-lever`

## Install

```bash
npx shadcn@latest add @bevel/toggle-lever
```

npm dependencies (installed by the CLI): `@base-ui/react`, `cn`.

## Anatomy

```tsx
<ToggleLeverField>
  <ToggleLeverLabel />
  <ToggleLeverDescription />
  <ToggleLever />
</ToggleLeverField>
```

## Parts

| Part | Renders | Description |
| --- | --- | --- |
| `ToggleLever` | Switch | checked, defaultChecked, onCheckedChange, disabled, name. size md prints OFF and ON on the plate; sm is lever and lamp only. Space flips it. Alone, give it an aria-label. |
| `ToggleLeverField` | Field.Root | A settings row: label and description on the left, the lever on the right. disabled locks the row. |
| `ToggleLeverLabel` | Field.Label | Names the switch. Clicking it throws the lever. |
| `ToggleLeverDescription` | Field.Description | Describes the switch. |

## Example: Notification settings

A lever per row, and a master lever that pauses them all.

```tsx
"use client"

import * as React from "react"
import { ToggleLever, ToggleLeverDescription, ToggleLeverField, ToggleLeverLabel } from "@/components/ui/toggle-lever"

const settings = [
  { id: "failures", label: "Run failures", description: "The moment an agent run fails.", on: true },
  { id: "approvals", label: "Approvals waiting", description: "When an agent stops to ask you.", on: true },
  { id: "digest", label: "Weekly digest", description: "Runs, spend and failures, every Monday.", on: false },
  { id: "product", label: "Product news", description: "New models and features, about monthly.", on: false },
]

/** Notification settings: one lever per row, and a master lever that silences them all. */
export function ToggleLeverNotifications() {
  const [paused, setPaused] = React.useState(false)
  return (
    <div className="flex w-full flex-col gap-4 rounded-xl border bg-card p-5">
      <ToggleLeverField>
        <ToggleLeverLabel className="font-semibold">Email notifications</ToggleLeverLabel>
        <ToggleLeverDescription>{paused ? "Paused. Nothing will be sent." : "Sent to you@acme.com."}</ToggleLeverDescription>
        <ToggleLever checked={!paused} onCheckedChange={(on) => setPaused(!on)} />
      </ToggleLeverField>
      <div className="flex flex-col gap-4 border-t pt-4">
        {settings.map((s) => (
          <ToggleLeverField key={s.id} name={s.id} disabled={paused}>
            <ToggleLeverLabel>{s.label}</ToggleLeverLabel>
            <ToggleLeverDescription>{s.description}</ToggleLeverDescription>
            <ToggleLever size="sm" defaultChecked={s.on} />
          </ToggleLeverField>
        ))}
      </div>
    </div>
  )
}
```