Liking cljdoc? Tell your friends :D

x-checkbox

An accessible, themeable checkbox control that supports checked, indeterminate, disabled, read-only, and required states. Fires cancelable request events before state changes, allowing host code to intercept. Text in the default slot is the label next to the box, and a click on it toggles the checkbox.


Tag

<x-checkbox></x-checkbox>

Attributes

AttributeTypeDefaultDescription
checkedbooleanfalseWhether the checkbox is checked. Present means checked, whatever its text, as in HTML.
indeterminatebooleanfalseIndeterminate (mixed) state — overrides checked visually
disabledbooleanfalseDisables interaction
readonlybooleanfalsePrevents user toggling (still focusable)
requiredbooleanfalseMarks the field as required; the element is invalid when unchecked
namestring—Form field name
valuestring"on"Value submitted with form data when checked
aria-labelstring—Accessible label
aria-describedbystring—References a describing element
aria-labelledbystring—References a labelling element

Properties

PropertyTypeReflects attribute
checkedbooleanchecked
indeterminatebooleanindeterminate
disabledbooleandisabled
readOnlybooleanreadonly
requiredbooleanrequired
namestringname
valuestringvalue

Events

EventCancelableDetail
x-checkbox-change-requestyes{ value, previousChecked, nextChecked } — call preventDefault() to block the toggle
x-checkbox-changeno{ value, checked } — fired after state has changed

Both events bubble and are composed.


Slots

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

Shadow parts

PartDescription
controlThe <button> with role="checkbox".
boxThe square that shows the state.
checkThe check mark and the indeterminate bar.
labelThe label next to the box. It is hidden when there is no label.

Label

  • A click on the box, on the label, on a wrapping <label> or on a <label for> toggles the checkbox.
  • A click on a link, a button or a form control inside the slot does not toggle the checkbox. That element keeps its own click.
  • --x-checkbox-label-gap sets the space between the box and the label. The default is var(--x-space-sm, 0.5rem).
  • When disabled, the label is dimmed like the box.

Toggle logic

  • When indeterminate is set, clicking always transitions to checked=true, indeterminate=false.
  • When checked, clicking transitions to checked=false, indeterminate=false.
  • When unchecked, clicking transitions to checked=true, indeterminate=false.

Form behaviour

  • formAssociated is true; the element participates in form submission.
  • The submitted value is the value attribute (default "on") when checked; nothing is submitted when unchecked.
  • On form reset, checked and indeterminate attributes are removed. The value attribute is not restored by reset (matching native <input type="checkbox"> behaviour).

Validation API

Like a native form control, x-checkbox 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.


Accessibility

  • The internal <button part="control"> carries role="checkbox" and aria-checked set to "true", "false", or "mixed".
  • tabindex="0" on the control when enabled; tabindex="-1" when disabled.
  • aria-disabled="true" on the control when disabled.
  • aria-required="true" on the control when required.
  • aria-readonly="true" on the control when readonly.
  • aria-label, aria-labelledby, and aria-describedby are forwarded from the host attribute to the control.
  • The control takes its accessible name from the slotted label through aria-labelledby. A host aria-labelledby or aria-label takes priority.
  • Keyboard: Space toggles; Enter toggles (unless readonly/disabled).

Examples

Basic states

<x-checkbox></x-checkbox>
<x-checkbox checked></x-checkbox>
<x-checkbox indeterminate></x-checkbox>
<x-checkbox disabled></x-checkbox>
<x-checkbox checked disabled></x-checkbox>

With a label

<x-checkbox name="agree" value="yes">I agree to the terms</x-checkbox>

<x-checkbox name="agree" value="yes">
  I agree to the <a href="/terms">terms</a>
</x-checkbox>

<label>
  <x-checkbox name="agree" value="yes" required></x-checkbox>
  I agree to the terms
</label>

Listening to changes

document.querySelector('x-checkbox').addEventListener('x-checkbox-change', e => {
  console.log('checked:', e.detail.checked, 'value:', e.detail.value);
});

Intercept and block toggle

checkbox.addEventListener('x-checkbox-change-request', e => {
  if (!canToggle) e.preventDefault();
});

ClojureScript (hiccup renderer)

[:x-checkbox {:checked "" :name "agree" :value "yes"
              :on-x-checkbox-change
              (fn [e]
                (swap! state assoc :agreed (.. e -detail -checked)))}]

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