Skip to content

x-switch.md

Latest commit

 

History

History
135 lines (103 loc) · 5.5 KB

x-switch.md

File metadata and controls

135 lines (103 loc) · 5.5 KB

x-switch

A toggle switch form control. Semantically a role="switch" button that reflects its state via the checked attribute. Form-associated (participates in <form> submission and reset).

Tag

<x-switch></x-switch>

Observed Attributes

Attribute Type Default Description
checked boolean absent Present → switch is on
disabled boolean absent Prevents interaction; control is inert
readonly boolean absent Prevents toggling without affecting form submission
required boolean absent Marks the field as required (must be checked for validity)
name string — Form field name
value string "on" Value submitted when checked
aria-label string — Forwarded to inner control
aria-describedby string — Forwarded to inner control
aria-labelledby string — Forwarded to inner control

Properties

Property Type Reflects attribute
checked boolean checked
disabled boolean disabled
readOnly boolean readonly
required boolean required
name string name
value string value

Events

x-switch-change-request

Fired before the state changes. Cancelable — call event.preventDefault() to block the toggle.

el.addEventListener('x-switch-change-request', (e) => {
  console.log(e.detail.previousChecked, e.detail.nextChecked, e.detail.value);
  e.preventDefault(); // optional: block the toggle
});
Detail field Type Description
value string Current form value
previousChecked boolean State before toggle
nextChecked boolean State after toggle (if not blocked)

x-switch-change

Fired after the state has changed. Not cancelable.

el.addEventListener('x-switch-change', (e) => {
  console.log(e.detail.checked, e.detail.value);
});
Detail field Type Description
value string Form value
checked boolean New checked state

Shadow Parts

Part Element Description
control button Interactive switch root
track span The pill-shaped track
thumb span The sliding thumb

CSS Custom Properties

Property Default Description
--x-switch-track-width 44px Track width
--x-switch-track-height 24px Track height
--x-switch-thumb-size 18px Thumb diameter
--x-switch-thumb-offset 3px Thumb inset from track edge
--x-switch-track-radius 999px Track border radius
--x-switch-track-bg #d1d5db Track background (off)
--x-switch-track-bg-checked #2563eb Track background (on)
--x-switch-thumb-bg #ffffff Thumb background
--x-switch-focus-ring #60a5fa Focus ring color
--x-switch-disabled-opacity 0.45 Opacity when disabled

Dark-mode overrides are applied automatically via @media (prefers-color-scheme: dark).

Accessibility

  • Inner button carries role="switch" and aria-checked.
  • aria-disabled, aria-required, aria-readonly are kept in sync.
  • aria-label, aria-labelledby, aria-describedby are forwarded to the inner button.
  • A <label for="..."> in the document is automatically wired via aria-labelledby.
  • Keyboard: Space and Enter toggle the switch.
  • Animations respect @media (prefers-reduced-motion: reduce).

Form participation

x-switch is a form-associated custom element. It submits name=value when checked, nothing when unchecked. It responds to formResetCallback and formDisabledCallback.

Usage examples

<!-- Basic -->
<x-switch name="notifications"></x-switch>

<!-- Pre-checked -->
<x-switch name="dark-mode" checked></x-switch>

<!-- With label -->
<label for="sw1">Enable alerts</label>
<x-switch id="sw1" name="alerts"></x-switch>

<!-- Disabled -->
<x-switch name="feature" disabled checked></x-switch>

<!-- Custom value -->
<x-switch name="theme" value="dark"></x-switch>

<!-- React to changes -->
<script>
  import '@vanelsas/baredom/x-switch';
  const sw = document.querySelector('x-switch');
  sw.addEventListener('x-switch-change', (e) => {
    console.log('now:', e.detail.checked);
  });
</script>