Checkbox

Checkbox component for toggling a single on/off choice, with an optional label and native form support.

Use when you need a single on/off toggle with a label that participates in native forms: <r-checkbox> reports its checked state to FormData and is keyboard-operable.

Quick Start

Basic Usage

<r-checkbox>Remember me</r-checkbox>

The default slot content becomes the checkbox label.

API Reference

Properties

The checked and value attributes are kept in sync: setting one updates the other. When checked, value is 'true'; when unchecked, value is 'false'.

Checked State checked

<r-checkbox checked="true">Checked</r-checkbox> <r-checkbox checked="false">Unchecked</r-checkbox>

Value value

<r-checkbox value="true">Value true</r-checkbox> <r-checkbox value="false">Value false</r-checkbox>

Disabled State disabled

<r-checkbox checked="true" disabled>Checked</r-checkbox> <r-checkbox checked="false" disabled>Unchecked</r-checkbox>

Custom Styling sheet

The sheet attribute injects CSS into the shadow DOM, letting you target internal parts by their class names.

<r-checkbox checked="true" sheet=".ran-checkbox-label { color: #006bff; }">Themed label</r-checkbox>

Events

change

Fired when the checkbox is toggled (by click or by pressing Space/Enter). The event is a CustomEvent whose detail carries the new checked state:

detail: {
  checked: boolean; // the checkbox's checked state after the toggle
}

A disabled checkbox does not fire change.

<r-checkbox onchange="handleChange(event)">Toggle me</r-checkbox>

<script>
  function handleChange(event) {
    console.log('checked:', event.detail.checked);
  }
</script>

Slots

Form Association

r-checkbox is a form-associated custom element (formAssociated = true). It relays its checked state through ElementInternals.setFormValue, so it participates in native forms and is collected by new FormData(form) when it's a real descendant of a native <form>. Following native checkbox semantics, it contributes its value only when checked.

The host itself carries the accessible checkbox semantics: role="checkbox", aria-checked, aria-disabled, and keyboard operability (toggle on Space or Enter).

Reset: a native form.reset() restores the checked state the box had when it first connected, via formResetCallback().

Validation: required makes an unchecked box invalid via ElementInternals.setValidity(), visible to form.checkValidity()/form.reportValidity(); a disabled box never blocks validation. checkValidity(), reportValidity(), validity, and validationMessage are exposed on the element, same as a native field.

<form>
  <r-checkbox name="terms" required>I agree to the terms</r-checkbox>
  <button type="submit">Submit</button>
</form>

CSS Parts

Style the internal structure with the ::part() selector:

r-checkbox::part(inner) {
  border-radius: 50%;
}
r-checkbox::part(label) {
  font-weight: 600;
}

Styling

<r-checkbox> exposes 32 CSS custom properties of its own, plus the semantic tokens it reads from the theme. Set one anywhere it inherits from, such as :root, a wrapper, or the element:

r-checkbox {
  --ran-checkbox-color: var(--ran-color-text-secondary);
}

Parts: checkbox · inner · input · label · wrapper

The full list is in style tokens; which token to reach for is the design system.

Best Practices

• Label your checkboxes: Provide slotted text so the control has an accessible name.
• Checked vs. value: Use checked for boolean state; read value ('true' / 'false') when collecting form data.
• Disabled State: Use disabled when the choice is unavailable.
• Listen to change: Read event.detail.checked rather than re-querying the DOM.
• Forms: Drop r-checkbox inside a <form>; its value is collected automatically when checked. See Forms for the serializeForm() helper that turns a submit into a plain object.