Skip to content

Checkbox ​

A customizable boolean form control with indeterminate state support, plus a group wrapper for managing multi-selection lists.

  • ore-checkbox: standalone checkbox for a single boolean value.
  • ore-checkbox-group: form-associated <fieldset> wrapper that manages a set of checkboxes, propagates color, size, and disabled to all children, and tracks checked values as a comma-separated values string.

Checkbox ​

Colors ​

Six semantic colors to match your design language or validation state.

Full width

Sizes ​

Full width

Indeterminate ​

Use the indeterminate state for "select all" controls where only some items in a sub-list are checked. First click resolves to checked; subsequent clicks toggle normally.

Full width

States ​

Disabled ​

Full width

Helper & Error Text ​

Provide contextual feedback directly below the checkbox.

Full width

Required ​

Set required to fail constraint validation while unchecked: the classic "I agree to the terms" consent checkbox. A native <form> blocks submission and checkValidity()/reportValidity() return false until it is checked; resetting the ancestor form restores its initial state.

Full width

Listening for Changes ​

js
const checkbox = document.querySelector('ore-checkbox');
checkbox.addEventListener('change', (e) => {
  console.log('checked:', e.currentTarget.checked);
  console.log('value:', e.currentTarget.value);
});

Checkbox Group ​

ore-checkbox-group wraps ore-checkbox elements in a <fieldset>. Set values to a comma-separated string to pre-select options, and set name when you want the group to submit with a form. Always provide a meaningful label on the group: it is the accessible name read before each option. Do not use ore-checkbox-group for mutually exclusive choices: use ore-radio-group instead.

Orientation ​

Full width

Use orientation="horizontal" only for short option labels that comfortably fit on one line.

Colors & Sizes ​

color and size set on the group propagate automatically to all child checkboxes.

Full width

Validation Feedback ​

Pair error with color="error" to reinforce validation failures visually.

Full width

Disabled ​

Disabling the group propagates to all child checkboxes.

Full width

Form Integration ​

The group's checked values are stored in the values attribute and submitted under the group's name as a comma-separated string with a native <form>. Prefer name on the group (not individual checkboxes) when submitting with a form.

Full width

Select All Pattern ​

Combine indeterminate state on a parent checkbox with a ore-checkbox-group to build a "select all" control. Use indeterminate on a "select all" checkbox to represent partial selection.

Full width

API Reference ​

ore-checkbox Attributes

AttributeTypeDefaultDescription
checkedbooleanfalseChecked state
indeterminatebooleanfalseIndeterminate (partially checked) state
disabledbooleanfalseDisable interaction
requiredbooleanfalseRequire this checkbox to be checked for native-form validation (e.g. a consent checkbox)
valuestring'on'Value submitted with the form
namestring''Form field name
color'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error'N/ASemantic color for the checked state
size'sm' | 'md' | 'lg''md'Checkbox size
helperstring''Helper text displayed below
errorstring''Error message (marks field invalid)

ore-checkbox Slots

SlotDescription
(default)Checkbox label text

ore-checkbox Parts

PartDescription
checkboxThe checkbox wrapper element
boxThe visual checkbox square
labelThe label text element

ore-checkbox Events

EventDetailDescription
change{ checked: boolean, value: string }Emitted when the checked state changes

ore-checkbox CSS Custom Properties

PropertyDescription
--checkbox-sizeCheckbox dimensions
--checkbox-radiusBorder radius
--checkbox-bgBackground color (unchecked state)
--checkbox-checked-bgBackground color (checked state)
--checkbox-border-colorBorder color
--checkbox-colorCheckmark icon color
--checkbox-font-sizeLabel font size

ore-checkbox-group Attributes

AttributeTypeDefaultDescription
labelstring''Legend text: required for accessibility
valuesstring''Comma-separated currently checked values (e.g. "a,b")
namestring''Form field name
orientation'vertical' | 'horizontal''vertical'Layout direction of options
color'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error'N/AColor propagated to all child checkboxes
size'sm' | 'md' | 'lg'N/ASize propagated to all child checkboxes
disabledbooleanfalseDisable all checkboxes in the group
requiredbooleanfalseMark the group as required
errorstring''Error message shown below the group (also sets ARIA invalid)
helperstring''Helper text (hidden when error is set)

ore-checkbox-group Slots

SlotDescription
(default)Place ore-checkbox elements here

ore-checkbox-group Events

EventDetailDescription
change{ values: string[] }Full array of currently checked values after any toggle

Accessibility ​

The checkbox components follow WCAG 2.1 Level AA standards.

ore-checkbox uses role="checkbox" with aria-checked set to "true", "false", or "mixed" for the indeterminate state. aria-labelledby links the label; aria-describedby links helper text; aria-errormessage links error text. aria-disabled reflects the disabled state. Keyboard interaction uses Space or Enter to toggle the focused checkbox, and Tab to move focus in and out.

ore-checkbox-group renders as a <fieldset> with a <legend> for the label attribute, providing proper screen reader grouping. Tab moves to the next checkbox within the group. aria-required and aria-invalid reflect the group validation state; aria-errormessage and aria-describedby link the text nodes.