The m3e-checkbox component enables users to select one or more options from a set.

npm i @m3e/checkbox

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

Checkboxes may be standalone, pre-checked, or indeterminate. When clicked, a cancellable input event is emitted followed by a change event. To cancel checked state changes, call preventDefault during input.

<m3e-checkbox></m3e-checkbox>
<m3e-checkbox checked></m3e-checkbox>
<m3e-checkbox indeterminate></m3e-checkbox>

Associate a label with a checkbox using the label element.

<label><m3e-checkbox></m3e-checkbox> Checkbox 1</label>
<m3e-checkbox id="chk2"></m3e-checkbox>
<label for="chk2">Checkbox 2</label>

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 checkbox. Associated labels are automatically styled to show disabled.

<label><m3e-checkbox disabled></m3e-checkbox>Disabled Checkbox 1</label>
<m3e-checkbox id="chk3" disabled></m3e-checkbox>
<label for="chk3">Disabled Checkbox 2</label>

Use the required attribute to control whether a checkbox must be checked. The invalid event fires when a form is submitted and the element fails constraint validation. When invalid, labels are automatically styled accordingly.

<form>
  <label>
    <m3e-checkbox name="accepted" required></m3e-checkbox>I accept the Terms and Conditions
  </label>
  <br />
  <m3e-button variant="filled" type="submit">Submit</m3e-button>
</form>

Checkboxes are given the ARIA role="checkbox" aligning its semantic identity with native checkbox controls. This ensures screen readers and assistive technologies interpret its behavior correctly.

The component manages and reflects its state via aria-checked:

• aria-checked="true" → checked
• aria-checked="false" → unchecked
• aria-checked="mixed" → indeterminate

When disabled using the disabled attribute, aria-disabled="true" is used to convey to assistive technologies that the checkbox 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/checkbox/dist/index.js"></script>

In addition, you must use an import map to include additional 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.