HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
CheckboxView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA box that is checked, unchecked, or indeterminate.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/checkbox'import'@fusion.dev/helix-headless/checkbox'Preview
API ReferenceRoothelix-checkboxA box that is checked, unchecked, or indeterminate.
PropTypeDescriptioncheckedbooleanWhether the control is checked.defaultCheckedbooleanDefaultfalseWhether the control starts checked. A form reset returns it to this state,
and to the checked attribute where this one is not written, as a native
checkbox resets to the checked it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.hintstringDefault""Help text shown under the control. A validation message replaces it.indeterminatebooleanDefaultfalseShows the box as neither checked nor unchecked.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.namestringDefault""The name the control's value is submitted under.readOnlybooleanDefaultfalseWhether a reader can see and focus the control and cannot change it. A
read-only control still submits its value.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.separation"filled"|"outlined"|"plain"How the option is set off from the page. plain shows the box next to its
label, and outlined and filled draw the option as a card.valuestringDefault"on"The value submitted when the box is checked.valueMissingMessagestringDefault"Tick this box to continue."The message shown when the field is required and empty.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The label.checkAn icon drawn as the mark while the box is checked, in place of the tick.dashAn icon drawn as the mark while the box is indeterminate, in place of the dash.feedbackThe message that says what is wrong, for content richer than a string. It shows while there is a message.hintHelp under the control, for content richer than the hint text.
EventTypeDescriptionchangeEventThe box was checked or unchecked. Relayed from the native input.helix-before-toggleHelixBeforeToggleEventThe box is about to be checked or unchecked. Cancelable: cancel it to keep its state.inputEventThe box was checked or unchecked.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.click() => voidTicks or clears the box, as click() does a native checkbox: passed to the control
inside, so the one click a listener hears is the control's, after it has
moved. See HostClickController.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestChecked(next: boolean) => booleanRequests a change to checked, and returns whether it was applied.resetChecked() => voidReturns the control to what its markup declared: defaultChecked where
default-checked is written, and the checked attribute where it is
not.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.toggleChecked() => booleanRequests the opposite of the current state.
PartDescriptionboxThe box drawn for the input, under the mark.controlThe native input.feedbackThe message that says what is wrong.fieldThe row that holds the box and its label. It is the card when separation is set.hintHelp text under the control, shown while there is no feedback.labelThe label next to the box.markThe check mark, or the dash when the box is indeterminate.mark-checkedAdded to mark while the box is checked.mark-dashAdded to mark while the box is indeterminate, and kept until the box is checked, so a mark that animates out leaves as the dash it was.mark-indeterminateAdded to mark while the box is indeterminate.
CSS PropertyDescription--checkbox-background-colorThe fill of the box. It stays the same when the box is checked.--checkbox-border-colorThe border color of the box, in every state.--checkbox-card-background-colorThe fill of the card.--checkbox-card-border-colorThe border color of the card.--checkbox-card-paddingThe padding of the card.--checkbox-checked-colorThe border color of a checked box when --checkbox-border-color is not set.--checkbox-icon-sizeThe width and height of an icon slotted into check or dash. It fills the box by default.--checkbox-mark-colorThe color of the check mark and the dash, and of an icon slotted into check or dash.--checkbox-sizeThe width and height of the box.
Custom stateDescriptioncheckedWhile the box is checked.has-checkAn icon is slotted into check.has-dashAn icon is slotted into dash.has-labelThe label slot has content, so the label is drawn.indeterminateWhile the box shows the dash, neither checked nor unchecked.invalidThe control has an error to show, from the browser's validation or from your feedback.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-checkboxA box that is checked, unchecked, or indeterminate.
PropTypeDescriptioncheckedbooleanWhether the control is checked.defaultCheckedbooleanDefaultfalseWhether the control starts checked. A form reset returns it to this state,
and to the checked attribute where this one is not written, as a native
checkbox resets to the checked it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.hintstringDefault""Help text shown under the control. A validation message replaces it.indeterminatebooleanDefaultfalseShows the box as neither checked nor unchecked.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.namestringDefault""The name the control's value is submitted under.readOnlybooleanDefaultfalseWhether a reader can see and focus the control and cannot change it. A
read-only control still submits its value.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.valuestringDefault"on"The value submitted when the box is checked.valueMissingMessagestringDefault"Tick this box to continue."The message reported when the field is required and the box is not ticked.
Absent, or empty, is this sentence, or the words registered for the page's
locale.
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescription(default)The label.checkAn icon drawn as the mark while the box is checked, in place of the tick.dashAn icon drawn as the mark while the box is indeterminate, in place of the dash.feedbackThe message that says what is wrong, for content richer than a string. It shows while there is a message.hintHelp under the control, for content richer than the hint text.
EventTypeDescriptionchangeEventThe box was checked or unchecked. Relayed from the native input.helix-before-toggleHelixBeforeToggleEventThe box is about to be checked or unchecked. Cancelable: cancel it to keep its state.inputEventThe box was checked or unchecked.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.click() => voidTicks or clears the box, as click() does a native checkbox: passed to the control
inside, so the one click a listener hears is the control's, after it has
moved. See HostClickController.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestChecked(next: boolean) => booleanRequests a change to checked, and returns whether it was applied.resetChecked() => voidReturns the control to what its markup declared: defaultChecked where
default-checked is written, and the checked attribute where it is
not.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.toggleChecked() => booleanRequests the opposite of the current state.
PartDescriptionboxThe box drawn for the input, under the mark.controlThe native input.feedbackThe message that says what is wrong.fieldThe row that holds the box and its label. It is the card when separation is set.hintHelp text under the control, shown while there is no feedback.labelThe label next to the box.markThe check mark, or the dash when the box is indeterminate.mark-checkedAdded to mark while the box is checked.mark-dashAdded to mark while the box is indeterminate, and kept until the box is checked, so a mark that animates out leaves as the dash it was.mark-indeterminateAdded to mark while the box is indeterminate.
Custom stateDescriptioncheckedWhile the box is checked.has-checkAn icon is slotted into check.has-dashAn icon is slotted into dash.has-labelThe label slot has content, so the label is drawn.indeterminateWhile the box shows the dash, neither checked nor unchecked.invalidThe control has an error to show, from the browser's validation or from your feedback.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionCardsCheckboxes drawn as cards, for options that need a description.ControlledA checkbox whose checked your code sets in response to helix-before-toggle.DisabledDisabled checkboxes, checked and unchecked.EventsThe events a click sends: helix-before-toggle with a boolean, then input and change.IndeterminateThe indeterminate state, for a parent option whose children are partly checked.InvalidA checkbox with a message that says what is wrong.PreviewOne checkbox with a label and a hint under it.PreviewOne checkbox with a label and a hint under it.RequiredA required checkbox, marked on its label, and the browser's message when it is left unchecked.