Switch

A binary state that takes effect immediately — feature flags, preference toggles, "do this, don't do this". Use a Switch when there's no Save button between the toggle and the effect.

import { Switch } from '@dashforge/tw';

<Switch label="Public access" />

Quick Start

Standalone:

const [enabled, setEnabled] = useState(false);

<Switch
  label="Public access"
  checked={enabled}
  onCheckedChange={setEnabled}
/>

Inside a form:

import { DashForm } from '@dashforge/forms';
import { Switch, Button } from '@dashforge/tw';

<DashForm onSubmit={updateSettings}>
  <Switch name="publicAccess" label="Public access" defaultChecked />
  <Switch name="emailNotifs" label="Email notifications" />
  <Button type="submit" color="primary">Save</Button>
</DashForm>

Switch vs Checkbox

Both are binary. The difference is intent:

When in doubt, ship a Checkbox. Switches are louder visually and should be reserved for "this matters, you're flipping it now" states.

Examples

import { Switch, Stack } from '@dashforge/tw';

<Stack gap={2}>
  <Switch name="dark-mode" label="Dark mode" />
  <Switch name="notifications" label="Email notifications" defaultChecked />
</Stack>

With helper text

<Switch
  label="Public access"
  helper="Anyone with the link can view this workspace."
  defaultChecked
/>

Helper text appears below the label in a muted color. Keep it under one sentence — Switches live in settings lists where vertical density matters.

Uncontrolled vs controlled

{/* Uncontrolled */}
<Switch label="Auto-publish" defaultChecked />

{/* Controlled — useful when the toggle drives a side effect immediately */}
<Switch
  label="Maintenance mode"
  checked={maintenanceMode}
  onCheckedChange={async (next) => {
    setMaintenanceMode(next);
    await api.setMaintenance(next);
  }}
/>

For switches that hit the network on every change, render a loading hint in helper while the request is in flight.

Disabled

import { Switch, Stack } from '@dashforge/tw';

<Stack gap={2}>
  <Switch name="state-off" label="Off" />
  <Switch name="state-on" label="On" defaultChecked />
  <Switch name="state-disabled-off" label="Disabled" disabled />
  <Switch name="state-disabled-on" label="Disabled + on" disabled defaultChecked />
</Stack>

<Switch
  label="Premium feature"
  helper="Upgrade your plan to enable."
  disabled
/>

Settings row pattern

The canonical use case — a settings card with toggle rows:

import { Switch, Stack, Box, Typography, Divider } from '@dashforge/tw';

<Box variant="outlined" rounded="md">
  <Stack direction="row" align="center" justify="between" gap={3} sx="p-4">
    <Stack gap={0}>
      <Typography variant="body2">Email notifications</Typography>
      <Typography variant="caption" color="muted">
        Send me product updates once a week.
      </Typography>
    </Stack>
    <Switch name="email-notif" defaultChecked />
  </Stack>
  <Divider />
  <Stack direction="row" align="center" justify="between" gap={3} sx="p-4">
    <Stack gap={0}>
      <Typography variant="body2">Two-factor auth</Typography>
      <Typography variant="caption" color="muted">
        Require a one-time code at sign-in.
      </Typography>
    </Stack>
    <Switch name="2fa" />
  </Stack>
</Box>

<div className="rounded-xl border border-neutral-200 dark:border-neutral-700 p-6 space-y-3">
  <h3 className="text-lg font-semibold">Workspace settings</h3>

  <Switch name="publicAccess"
    label="Public access"
    helper="Anyone with the link can view."
    defaultChecked
  />
  <Switch name="emailNotifs"
    label="Email notifications"
    helper="Weekly activity digest."
  />
  <Switch name="auditLog"
    label="Audit log"
    helper="Record every action by every user. May impact performance."
  />
</div>

RBAC gating

<Switch
  name="maintenanceMode"
  label="Maintenance mode"
  access={{ requires: 'workspace.admin', when: 'denied:disable' }}
/>

Three when modes ('denied:hide' | 'denied:disable' | 'denied:readonly') — same semantics as Button, TextField, Checkbox.

API

Props

Slots

root (wrapping <label>) · track (the rail) · thumb (the moving circle) · label · helper

Notes

• Backed by Radix (@radix-ui/react-switch) — role="switch", aria-checked, keyboard navigation (Space and Enter to toggle), focus management are all the primitive's responsibility.
• The thumb animation uses transform: translateX + a hardware-accelerated transition — no layout thrash at 60fps even on cheap Android devices.
• The click target spans the whole row (label + helper + track). Fat-finger friendly on touch.
• Form serialization: a hidden <input type="checkbox"> mirrors the Switch's state so native <form> submission works. Most apps use <DashForm> and never look at this — but it's there if you need it.
• Async toggles: if onCheckedChange triggers an API call, render the loading hint in helper AND consider disabled={isPending} so the user doesn't double-tap during the request.