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.
<x-checkbox></x-checkbox>
| Attribute | Type | Default | Description |
|---|
checked | boolean | false | Whether the checkbox is checked. Present means checked, whatever its text, as in HTML. |
indeterminate | boolean | false | Indeterminate (mixed) state — overrides checked visually |
disabled | boolean | false | Disables interaction |
readonly | boolean | false | Prevents user toggling (still focusable) |
required | boolean | false | Marks the field as required; the element is invalid when unchecked |
name | string | — | Form field name |
value | string | "on" | Value submitted with form data when checked |
aria-label | string | — | Accessible label |
aria-describedby | string | — | References a describing element |
aria-labelledby | string | — | References a labelling element |
| Property | Type | Reflects attribute |
|---|
checked | boolean | checked |
indeterminate | boolean | indeterminate |
disabled | boolean | disabled |
readOnly | boolean | readonly |
required | boolean | required |
name | string | name |
value | string | value |
| Event | Cancelable | Detail |
|---|
x-checkbox-change-request | yes | { value, previousChecked, nextChecked } — call preventDefault() to block the toggle |
x-checkbox-change | no | { value, checked } — fired after state has changed |
Both events bubble and are composed.
| Slot | Description |
|---|
| (default) | The label next to the box. Text, links and other inline content are allowed. |
| Part | Description |
|---|
control | The <button> with role="checkbox". |
box | The square that shows the state. |
check | The check mark and the indeterminate bar. |
label | The label next to the box. It is hidden when there is no 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.
- 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.
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).
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.
- 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).
<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>
<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>
document.querySelector('x-checkbox').addEventListener('x-checkbox-change', e => {
console.log('checked:', e.detail.checked, 'value:', e.detail.value);
});
checkbox.addEventListener('x-checkbox-change-request', e => {
if (!canToggle) e.preventDefault();
});
[:x-checkbox {:checked "" :name "agree" :value "yes"
:on-x-checkbox-change
(fn [e]
(swap! state assoc :agreed (.. e -detail -checked)))}]