Switch
<esp-switch>
A toggle switch for boolean on/off values. Uses a CSS-only track-and-thumb design with a smooth sliding transition. Functionally equivalent to a checkbox but visually communicates an immediate state change rather than a deferred selection.
Slots
<esp-switch> has a slot:
Default
The label text for the switch.
Attributes
<esp-switch> has the following attributes:
checked
checked has a default value of false.
Whether the switch is in the on state.
value
value has a default value of "".
The value associated with this switch. Submitted with the form when the switch is on.
name
name has a default value of "".
The name used when the switch participates in a <form>.
required
required has a default value of false.
When true, the switch must be on before the form can be submitted.
required-message
required-message has a default value of "".
A custom message to display when the switch is required but
not on. Defaults to "Please toggle this switch to continue."
when not set.
disabled
disabled has a default value of false.
Controls whether the switch is disabled.
Methods
<esp-switch> has the following methods:
focus
Focus the switch control.
validate
Re-run constraint validation and dispatch validity-changed.
checkValidity
Check whether the current state is valid (delegates to ElementInternals).
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
Events
<esp-switch> emits the following events:
value-changed
value-changed is of type CustomEvent<{ checked: boolean; value: string }>.
Fired when the switch is toggled. The detail contains the new checked state and the switch value.
CSS Properties
<esp-switch> has the following CSS properties:
--esp-switch-width
The width of the switch track. Defaults to calc(var(--esp-size-normal-to-medium) * 1.75).
--esp-switch-height
The height of the switch track. Defaults to var(--esp-size-normal-to-medium).
--esp-switch-thumb-size
The diameter of the thumb. Defaults to calc(var(--esp-switch-height) - 4px).
--esp-switch-track-color
The track background color when the switch is off. Defaults to var(--esp-color-border).
--esp-switch-track-color-on
The track background color when the switch is on. Defaults to var(--esp-color-action-background).
--esp-switch-thumb-color
The thumb color. Defaults to var(--esp-color-layer-1).
--esp-switch-focus-shadow
The color of the focus ring shadow. Defaults to var(--esp-color-shadow).
--esp-field-background
Background color of the shared field shell. Defaults to var(--esp-color-layer-2).
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).