The m3e-switch component is nn on/off control that can be toggled by clicking.

npm i @m3e/switch

This section outlines usage examples and configuration guidance for the components in this package.

Use the m3e-switch component to create a switch (also known as a slide toggle). Use the checked attribute to indicate whether the switch is "on". When clicked, a cancellable input event is emitted followed by a change event. To cancel checked state changes, call preventDefault during input.

<m3e-switch checked></m3e-switch>

Associate a label with a switch using the label element.

<label><m3e-switch></m3e-switch> Switch 1</label>
<m3e-switch id="switch2"></m3e-switch>
<label for="switch2"> Switch 2</label>

You can control the icons to present using the icons attribute. Supports values include none (default), selected, and both.

<m3e-switch icons="selected" checked></m3e-switch>
<m3e-switch icons="both"></m3e-switch>

This component participates in form submission as a form-associated custom element (FACE), contributing its state to the form data. The name attribute defines the key under which the component's value is submitted in a form. When checked and not disabled, value (defaults to "on") is submitted.

The component honors the disabled state as a property-only control. When disabled at runtime, it does not sprout a disabled attribute into the DOM.

Use the disabled attribute to disable a switch. Associated labels are automatically styled to show disabled.

<label><m3e-switch disabled></m3e-switch>Disabled Switch 1</label>
<m3e-switch id="chk3" disabled></m3e-switch>
<label for="chk3">Disabled Switch 2</label>

Switches are given the ARIA role="switch" aligning with their semantic purpose as binary state toggles. This role communicates to assistive technologies that the component represents a two-state control, similar to a checkbox but with a distinct interaction model.

The component manages and reflects its state via the aria-checked attribute, where aria-checked="true" indicates the switch is checked (on), and aria-checked="false" indicates it is unchecked (off).

When disabled using the disabled attribute, aria-disabled="true" is used to convey to assistive technologies that the switch is disabled. When disabled at runtime, it does not sprout a disabled attribute into the DOM.

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/switch/dist/index.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

For production, use index.min.js for faster load times.

This package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.