@papit/switch

A binary on/off toggle control implemented as a Web Component. Use a switch instead of a checkbox when the meaning is stateful rather than selection — for example “Notifications on” reads more naturally than “Notifications checked”.

The component follows the WAI-ARIA Switch Pattern, supports keyboard interaction, and participates in HTML forms like a native input.

See the pattern: https://www.w3.org/WAI/ARIA/apg/patterns/switch/

Installation

npm install @papit/switch

Usage

Import

import "@papit/switch";

Basic example

<pap-switch></pap-switch>

With label

<label>
  Notifications
  <pap-switch></pap-switch>
</label>

Default checked

<pap-switch defaultchecked></pap-switch>

Form Support

pap-switch participates in forms using ElementInternals.

When the switch is on, it submits "true" as its form value.

<form>
  <pap-switch name="notifications"></pap-switch>

  <button type="submit">Submit</button>
</form>

Example submitted data:

{
  "notifications": "true"
}

If the switch is off, no value is submitted — the same behavior as a native checkbox.

Attributes / Properties

| Attribute | Property | Type | Description | | ---------------- | ---------------- | --------- | ------------------------------------- | | checked | checked | boolean | Current state of the switch | | defaultchecked | defaultChecked | boolean | Initial state used when a form resets | | disabled | disabled | boolean | Prevents interaction | | readonly | — | boolean | Prevents toggling but allows focus |

Events

| Event | Description | | -------- | --------------------------------------- | | change | Fired whenever the switch state changes |

Example:

const el = document.querySelector("pap-switch");

el.addEventListener("change", () => {
  console.log("Switch state:", el.checked);
});

Keyboard Interaction

| Key | Behavior | | ------- | ----------------- | | Space | Toggle the switch | | Enter | Toggle the switch |

During keyboard press the component temporarily exposes an internal active state for styling.

Accessibility

This component implements the ARIA Switch Pattern and automatically manages:

• role="switch"
• aria-checked
• keyboard interaction
• focus behavior

Reference:

https://www.w3.org/WAI/ARIA/apg/patterns/switch/

Styling

The component uses a constructed stylesheet and exposes internal states that can be styled:

pap-switch:state(checked) {
  /* some style goes here */
}

pap-switch:state(active) {
  /* some style goes here */
}

Example:

pap-switch:state(checked) {
  background: green;
}

Contributing

Contributions are welcome.

Please ensure:

• tests pass
• linting passes
• behavior follows the ARIA switch pattern

Submit pull requests through the GitHub repository.

License

Licensed under the @Papit License 1.0 Copyright (c) 2024 Henry Pap (@onkelhoy)

Key points

• ✅ Free to use in commercial projects
• ✅ Free to modify and distribute
• ✅ Attribution required
• ❌ Cannot resell the component itself as a standalone product

See the LICENSE file for full details.

Related Components

• @papit/web-component Core utilities, decorators, and base component class.

Support

For issues, questions, or contributions, please visit the GitHub repository.