Liking cljdoc? Tell your friends :D

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). Text in the default slot is the label next to the switch, and a click on it toggles the switch.

Tag

<x-switch></x-switch>

Observed Attributes

AttributeTypeDefaultDescription
checkedbooleanabsentPresent → switch is on
disabledbooleanabsentPrevents interaction; control is inert
readonlybooleanabsentPrevents toggling without affecting form submission
requiredbooleanabsentMarks the field as required (must be checked for validity)
namestring—Form field name
valuestring"on"Value submitted when checked
aria-labelstring—Forwarded to inner control
aria-describedbystring—Forwarded to inner control
aria-labelledbystring—Forwarded to inner control

Properties

PropertyTypeReflects attribute
checkedbooleanchecked
disabledbooleandisabled
readOnlybooleanreadonly
requiredbooleanrequired
namestringname
valuestringvalue

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 fieldTypeDescription
valuestringCurrent form value
previousCheckedbooleanState before toggle
nextCheckedbooleanState 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 fieldTypeDescription
valuestringForm value
checkedbooleanNew checked state

Slots

SlotDescription
(default)The label next to the switch. Text, links and other inline content are allowed.

Shadow Parts

PartElementDescription
controlbuttonInteractive switch root
trackspanThe pill-shaped track
thumbspanThe sliding thumb
labelspanThe label next to the switch. It is hidden when there is no label.

Label

  • A click on the switch, on the label, on a wrapping <label> or on a <label for> toggles the switch.
  • A click on a link, a button or a form control inside the slot does not toggle the switch. That element keeps its own click.
  • When disabled, the label is dimmed like the switch.

CSS Custom Properties

PropertyDefaultDescription
--x-switch-track-width44pxTrack width
--x-switch-track-height24pxTrack height
--x-switch-thumb-size18pxThumb diameter
--x-switch-thumb-offset3pxThumb inset from track edge
--x-switch-track-radiusvar(--x-radius-full,999px)Track border radius
--x-switch-track-bgvar(--x-color-border,#d1d5db)Track background (off)
--x-switch-track-bg-checkedvar(--x-color-primary,#2563eb)Track background (on)
--x-switch-thumb-bgvar(--x-color-bg,#ffffff)Thumb background
--x-switch-focus-ringvar(--x-color-focus-ring,#60a5fa)Focus ring color
--x-switch-disabled-opacity0.45Opacity when disabled
--x-switch-label-gapvar(--x-space-sm,0.5rem)Space between the switch and the label

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.
  • The inner button takes its accessible name from the slotted label through aria-labelledby. A host aria-labelledby or aria-label takes priority.
  • 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.

Validation API

Like a native form control, x-switch exposes read-only validity, validationMessage, willValidate, form and labels, plus checkValidity() and reportValidity(). All seven delegate to the element's ElementInternals, so el.checkValidity() answers the same question a submit attempt would.

Usage examples

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

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

<!-- With label -->
<x-switch name="alerts">Enable 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>

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close