van-switch

A form-control switch component for VanJS.

Install

bun add van-switch vanjs-core

Usage

import van from "vanjs-core";
import { Switch } from "van-switch";
import "van-switch/styles.css";

const notifications = van.state(false);

document.body.append(
  Switch({
    checked: notifications,
    name: "notifications",
    label: "Notifications",
    description: "Receive product updates and account alerts.",
    onChange: (checked) => {
      console.log(checked);
    },
  }),
);

The exported component is named Switch.

Controlled State

Pass a VanJS State<boolean> as checked.

const enabled = van.state(false);

Switch({
  checked: enabled,
  label: "Enabled",
});

enabled.val = true;

Uncontrolled State

Omit checked and use defaultChecked when the switch can own its state.

Switch({
  defaultChecked: true,
  label: "Online",
});

Forms

Switch renders a native checkbox input with role="switch", so it supports name, value, form, disabled, required, and browser form submission.

form(
  Switch({
    name: "terms",
    value: "accepted",
    required: true,
    label: "Accept terms",
  }),
);

Unchecked switches are omitted from FormData, matching native checkbox behavior.

External Labels

label and description are convenience props. You can also compose labels externally.

label(
  span({ id: "billing-label" }, "Billing alerts"),
  Switch({
    ariaLabelledBy: "billing-label",
  }),
);

Every switch should have visible label text, ariaLabel, or ariaLabelledBy.

Styling

Import the stylesheet once:

import "van-switch/styles.css";

Defaults are monochromatic and adapt to prefers-color-scheme: dark.

Override variables on :root, a wrapper, or the switch itself:

.billing-toggle {
  --van-switch-track-on: #111111;
  --van-switch-radius: 6px;
  --van-switch-thumb-radius: 4px;
}

Available variables:

--van-switch-width
--van-switch-height
--van-switch-padding
--van-switch-thumb-size
--van-switch-radius
--van-switch-thumb-radius
--van-switch-track-off
--van-switch-track-on
--van-switch-track-disabled
--van-switch-thumb
--van-switch-thumb-disabled
--van-switch-text
--van-switch-muted
--van-switch-focus-ring
--van-switch-duration
--van-switch-easing
--van-switch-gap

API

type SwitchProps = {
  checked?: State<boolean>;
  defaultChecked?: boolean;
  onChange?: (checked: boolean, event: Event) => void;
  label?: string | Node;
  description?: string | Node;
  id?: string;
  name?: string;
  value?: string;
  form?: string;
  disabled?: boolean;
  required?: boolean;
  autofocus?: boolean;
  class?: string;
  className?: string;
  style?: string | Partial<CSSStyleDeclaration>;
  ariaLabel?: string;
  ariaLabelledBy?: string;
  ariaDescribedBy?: string;
};