Switch

A toggle for a single on/off setting. Built on base-ui Switch — keyboard support, focus management, and ARIA wiring come for free.

Reach for a Switch when flipping it takes effect immediately (a preference, a feature toggle) — “Email me tracking updates”, “Require signature”. Use a Checkbox instead when the choice is part of a form the user submits, or when it sits in a list of selectable options. One rule of thumb: a switch is a setting, a checkbox is a selection.

Basic

Pair a Switch with a Label — match the label’s htmlFor to the switch’s id so clicking the text also flips it. It’s uncontrolled by default.

Email me tracking updates

import { Label, Switch } from "@vesyl/ui-next";

export default function SwitchBasic() {
  return (
    <div className="flex items-center gap-3">
      <Switch id="tracking-updates" />
      <Label htmlFor="tracking-updates">Email me tracking updates</Label>
    </div>
  );
}

Default on

Pass defaultChecked to start in the on position while leaving the switch uncontrolled.

Require signature on delivery

import { Label, Switch } from "@vesyl/ui-next";

export default function SwitchDefaultOn() {
  return (
    <div className="flex items-center gap-3">
      <Switch id="signature" defaultChecked />
      <Label htmlFor="signature">Require signature on delivery</Label>
    </div>
  );
}

Disabled

disabled blocks interaction and dims the track. It works in either state — use a forced-on disabled switch to show a setting that’s locked on (e.g. granted by a higher-level permission).

Add insurance (off)

Add insurance (on)

import { Label, Switch } from "@vesyl/ui-next";

export default function SwitchDisabled() {
  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-3">
        <Switch id="insurance-off" disabled />
        <Label htmlFor="insurance-off">Add insurance (off)</Label>
      </div>
      <div className="flex items-center gap-3">
        <Switch id="insurance-on" defaultChecked disabled />
        <Label htmlFor="insurance-on">Add insurance (on)</Label>
      </div>
    </div>
  );
}

Controlled

Drive the switch yourself with checked plus onCheckedChange — the handler receives the next boolean directly, no event unwrapping.

Auto-buy labels on fulfillment

Labels are bought manually.

import { useState } from "react";
import { Label, Switch } from "@vesyl/ui-next";

export default function SwitchControlled() {
  const [autoBuyLabels, setAutoBuyLabels] = useState(false);

  return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-3">
        <Switch
          id="auto-buy"
          checked={autoBuyLabels}
          onCheckedChange={setAutoBuyLabels}
        />
        <Label htmlFor="auto-buy">Auto-buy labels on fulfillment</Label>
      </div>
      <p className="text-muted-foreground text-sm">
        Labels {autoBuyLabels ? "purchase automatically" : "are bought manually"}.
      </p>
    </div>
  );
}

Settings list

The common pattern: a FieldGroup of horizontal Field rows, each with a FieldContent (title + description) on the left and a Switch on the right. Give each switch an aria-label so it’s named for screen readers.

Email me tracking updates

Get a message each time a shipment changes status.

Require signature on delivery

Carriers will collect a signature before releasing the package.

Auto-buy labels on fulfillment

Purchase the cheapest qualifying rate as soon as an order is marked fulfilled.

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldTitle,
  Switch,
} from "@vesyl/ui-next";

export default function SwitchSettingsList() {
  return (
    <FieldGroup className="w-full max-w-md">
      <Field orientation="horizontal">
        <FieldContent>
          <FieldTitle>Email me tracking updates</FieldTitle>
          <FieldDescription>
            Get a message each time a shipment changes status.
          </FieldDescription>
        </FieldContent>
        <Switch defaultChecked aria-label="Email me tracking updates" />
      </Field>
      <Field orientation="horizontal">
        <FieldContent>
          <FieldTitle>Require signature on delivery</FieldTitle>
          <FieldDescription>
            Carriers will collect a signature before releasing the package.
          </FieldDescription>
        </FieldContent>
        <Switch aria-label="Require signature on delivery" />
      </Field>
      <Field orientation="horizontal">
        <FieldContent>
          <FieldTitle>Auto-buy labels on fulfillment</FieldTitle>
          <FieldDescription>
            Purchase the cheapest qualifying rate as soon as an order is marked
            fulfilled.
          </FieldDescription>
        </FieldContent>
        <Switch aria-label="Auto-buy labels on fulfillment" />
      </Field>
    </FieldGroup>
  );
}

Reference

Switch

Extends base-ui Switch.Root props (minus onChange).

Prop	Type	Default	Description
`checked`	`boolean`	—	Checked state (controlled)
`defaultChecked`	`boolean`	`false`	Initial checked state (uncontrolled)
`onCheckedChange`	`(checked: boolean) => void`	—	Fires with the next checked state on toggle
`disabled`	`boolean`	`false`	Blocks interaction and dims the track
`size`	`"sm" \| "md"`	`"md"`	Track and thumb size; `sm` for dense rows
`className`	`string`	—	Merged onto the root