Skip to main content

Switch

Stable

Toggles a binary on/off state with immediate effect. The thumb translates with spring easing for a premium feel. Use when the change applies instantly — use Checkbox for form submissions.

Form elementInteractiveVhyxSeal

Interactive example

Notifications enabled
Toggle notifications

Import

tsx
import { Switch } from '@vhyxui/react'

States

OffOnDisabled offDisabled on
Off, On, Disabled off, Disabled on

Sizes

sm, md, lg

Props

PropTypeDefaultDescription
checkedboolean—Controlled on/off state.
defaultCheckedbooleanfalseDefault state for uncontrolled usage.
onCheckedChange(checked: boolean) => void—Called when the switch is toggled.
size'sm' | 'md' | 'lg''md'Size of the switch.
disabledbooleanfalseDisables interaction (from HTMLButtonElement).
asChildbooleanfalseRenders as the child element via Slot.
contractPartial<ComponentContract>—VhyxSeal contract override.
classNamestring—Additional CSS classes appended to the switch.

Also accepts all standard HTMLButtonElement attributes.

Accessibility

  • ✓ Renders as <button role="switch"> — correct semantics for a toggle.
  • ✓ aria-checked reflects the current on/off state automatically.
  • ✓ Always provide aria-label or pair with a visible <label> using htmlFor.
  • ✓ Focus ring via :focus-visible — visible on keyboard, hidden on mouse click.
  • ✓ Use Switch for immediate-effect settings. Use Checkbox for form values submitted on save.

Keyboard navigation

KeyAction
SpaceorEnterToggle the switch on or off.
TabMove focus to the next focusable element.
Shift + TabMove focus to the previous focusable element.

Agent contract

Default VhyxSeal contract shipped with every Switch.

Default contract
{
  "type": "input",
  "intent": "toggle-state",
  "description": "Toggles a binary on/off state immediately upon interaction",
  "requires": [],
  "requiredPermissions": [],
  "consequence": "Changes the boolean state of the controlled feature",
  "affects": [],
  "reversible": true,
  "safetyLevel": "low",
  "requiresConfirmation": false,
  "destructive": false,
  "contractVersion": "0.0.1",
  "fingerprint": "vhyxs_5ced5d92"
}

Theming

Override these CSS tokens to theme Switch.

--vhyx-color-accentTrack color when on
--vhyx-color-accent-hoverTrack hover color when on
--vhyx-color-bg-mutedTrack color when off
--vhyx-color-surfaceThumb color
--vhyx-radius-fullTrack and thumb border radius
--vhyx-duration-normalThumb slide duration
--vhyx-easing-springThumb slide easing
--vhyx-shadow-focusFocus ring

Examples

Settings panel

Push notifications
Dark mode
Marketing emails
Multiple toggles in a settings list

Inside a Field

tsx
<Field name="notifications" label="Push notifications" hint="Receive alerts for important activity">
  <Switch
    checked={form.watch('notifications')}
    onCheckedChange={v => form.setValue('notifications', v)}
    aria-label="Enable push notifications"
  />
</Field>