Switch

import "@taprootio/espalier/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.

Text mode

Set mode="text" with off-label and on-label to render a two-option text toggle instead of a track and thumb. This is ideal for binary choices like a billing-period selector:

The slotted text is visually hidden in text mode and folded into the control's accessible label together with the current selected option. Screen readers will announce both the label and the active choice while the off-label / on-label text is presented visually.

Slots

<esp-switch> has a slot:

Default

The label text for the switch. In default mode this renders beside the track; in text mode it is visually hidden and included in the control's accessible label.

Attributes

<esp-switch> has the following attributes:

mode

mode has a default value of "switch".

The visual presentation of the switch.

"switch" (default) renders a track-and-thumb toggle.
"text" renders two side-by-side text labels with a sliding highlight behind the active one.

off-label

off-label has a default value of "".

Label shown for the unchecked (off) state when mode="text".

on-label

on-label has a default value of "".

Label shown for the checked (on) state when mode="text".

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.

intent

intent has a default value of undefined.

The element's intent — its meaning: neutral (no pin), or success, warning, danger, info — each pinned to its fixed status family (blue for info), retunable per theme via intents. On token-emitting controls a non-neutral intent pins the filled-action pair to that family, derived over the governing zone's theme; class-styled chrome (badges, callouts, status pills) opts out of inline emission and renders its treatment from CSS classes instead. An intent never repaints the surrounding zone, which is what contexts are for. Removing the attribute restores the element's own default intent.

context

context has a default value of undefined.

A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.

Methods

<esp-switch> has the following methods:

focus

Focus the switch control.

validate

Re-run constraint validation and dispatch esp-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:

esp-value-changed

esp-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.

esp-validity-changed

esp-validity-changed is of type CustomEvent<{ valid: boolean; message: string }>.

Fired whenever constraint validation runs.

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-switch-text-padding

Padding inside each text-mode label cell. Defaults to var(--esp-size-tiny) var(--esp-size-small).

--esp-switch-text-font-size

Font size for text-mode labels. Defaults to var(--esp-size-font).

--esp-switch-text-active-color

Text color of the active label in text mode. Defaults to var(--esp-color-action-text).

--esp-switch-text-inactive-color

Text color of the inactive label in text mode. Defaults to var(--esp-color-layer-1).

--esp-switch-text-highlight-color

Background color of the sliding highlight in text mode. Defaults to var(--esp-color-action-background).

--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).