HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
SwitchView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA control that turns something on or off.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/switch'import'@fusion.dev/helix-headless/switch'Preview
API ReferenceRoothelix-switchA control that turns something on or off.
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.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"Value submitted when the switch is on.valueMissingMessagestringDefault"Turn this on 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 that names what the switch turns on.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.offAn icon on the thumb while the switch is off.onAn icon on the thumb while the switch is on.
EventTypeDescriptionchangeEventSent from the input after the state changes.helix-before-toggleHelixBeforeToggleEventFired before the state changes, and cancelable.inputEventSent after the state changes.
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() => voidTurns the switch on or off, 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.
PartDescriptioncontrolThe input.feedbackThe message that says what is wrong.fieldThe row: the track and its label.hintHelp under the control, while nothing is wrong.labelThe label beside the track.thumbThe thumb that travels along the track, and the icon on it.trackThe track.
CSS PropertyDescription--switch-block-sizeHeight of the track. The width follows it.--switch-icon-colorColor of the icon on the thumb. Without it, the icon is muted while off and takes the on color while on.--switch-inline-sizeLength of the track. Set it to override the length derived from the height.--switch-on-colorFill when the switch is on.--switch-thumb-colorColor of the thumb, in both states.
Custom stateDescriptioncheckedWhile it is on.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-switchA control that turns something on or off.
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.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"Value submitted when the switch is on.valueMissingMessagestringDefault"Turn this on to continue."The message reported when the field is required and the switch is off.
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 that names what the switch turns on.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.
EventTypeDescriptionchangeEventSent from the input after the state changes.helix-before-toggleHelixBeforeToggleEventFired before the state changes, and cancelable.inputEventSent after the state changes.
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() => voidTurns the switch on or off, 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.
PartDescriptioncontrolThe input.feedbackThe message that says what is wrong.fieldThe row: the track and its label.hintHelp under the control, while nothing is wrong.labelThe label beside the track.trackThe track. Draw the thumb on the track itself, with ::part(track)::after in your stylesheet. This tier ships no CSS, so it renders no separate thumb element, which would be an empty child that costs your layout as much as any other child. ListItem measured that cost. A subclass that draws one returns it from renderThumb, as the styled switch does.
Custom stateDescriptioncheckedWhile it is on.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
NameDescriptionDisabledA disabled switch, on and off, because the two states look different.EventsSwitching sends helix-before-toggle, input, and change.IconsA switch with an icon on its thumb for each state: a sun while off and a moon while on.InvalidA switch with an error message that says it must be on.PreviewA setting that takes effect as soon as it is switched.PreviewA setting that takes effect as soon as it is switched.RequiredA switch that must be on before the form submits.