GitHub

Switch Toggle

An on/off switch for instant settings — a native <button role="switch"> with Space/Enter toggling and a sliding thumb. Form-associated; emits a composed change event.

Stable wc import '@esa/ecology/esa-switch-toggle'; Angular usage

Preview

<esa-switch-toggle label="Email notifications" checked></esa-switch-toggle>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-switch-toggle';

@Component({
  selector: 'app-switch-toggle-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-switch-toggle label="Email notifications" checked></esa-switch-toggle>
  `,
})
export class SwitchToggleDemo {}

Sizes

<esa-switch-toggle label="Extra small" size="xs" checked></esa-switch-toggle>
<esa-switch-toggle label="Small" size="sm" checked></esa-switch-toggle>
<esa-switch-toggle label="Medium" size="md" checked></esa-switch-toggle>
<esa-switch-toggle label="Large" size="lg" checked></esa-switch-toggle>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-switch-toggle';

@Component({
  selector: 'app-switch-toggle-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-switch-toggle label="Extra small" size="xs" checked></esa-switch-toggle>
    <esa-switch-toggle label="Small" size="sm" checked></esa-switch-toggle>
    <esa-switch-toggle label="Medium" size="md" checked></esa-switch-toggle>
    <esa-switch-toggle label="Large" size="lg" checked></esa-switch-toggle>
  `,
})
export class SwitchToggleDemo {}

Label position

Place the label after the track (default) or before it.

<esa-switch-toggle label="Label after" checked></esa-switch-toggle>
<esa-switch-toggle label="Label before" label-position="before" checked></esa-switch-toggle>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-switch-toggle';

@Component({
  selector: 'app-switch-toggle-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-switch-toggle label="Label after" checked></esa-switch-toggle>
    <esa-switch-toggle label="Label before" label-position="before" checked></esa-switch-toggle>
  `,
})
export class SwitchToggleDemo {}

States

<esa-switch-toggle label="Off"></esa-switch-toggle>
<esa-switch-toggle label="On" checked></esa-switch-toggle>
<esa-switch-toggle label="Disabled" disabled></esa-switch-toggle>
<esa-switch-toggle label="Disabled + on" disabled checked></esa-switch-toggle>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-switch-toggle';

@Component({
  selector: 'app-switch-toggle-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-switch-toggle label="Off"></esa-switch-toggle>
    <esa-switch-toggle label="On" checked></esa-switch-toggle>
    <esa-switch-toggle label="Disabled" disabled></esa-switch-toggle>
    <esa-switch-toggle label="Disabled + on" disabled checked></esa-switch-toggle>
  `,
})
export class SwitchToggleDemo {}

Form participation

A checked switch submits on under its name; off submits nothing. Submitting logs the alerts entry.

<form>
  <esa-switch-toggle label="Enable alerts" name="alerts" checked></esa-switch-toggle>
  <button type="submit">Submit</button>
</form>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-switch-toggle';

@Component({
  selector: 'app-switch-toggle-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <form>
      <esa-switch-toggle label="Enable alerts" name="alerts" checked></esa-switch-toggle>
      <button type="submit">Submit</button>
    </form>
  `,
})
export class SwitchToggleDemo {}

API

PropTypeDefaultDescription
label string '' Text rendered beside the track.
size 'xs' | 'sm' | 'md' | 'lg' 'md' Track and thumb size.
disabled boolean false Disables interaction.
name string | undefined — Form field name — the key this control submits under.
label-position 'before' | 'after' 'after' Whether the label sits before or after the track. Property: `labelPosition`.
checked boolean false On/off state of the switch.

Events

EventTypeDefaultDescription
change CustomEvent<{ checked: boolean }> — Fired when toggled. Composed and bubbling; detail.checked is the new state.
Binding these events from Angular

Every one of these is a CustomEvent, so the payload is on $event.detail — $event.target.value reads empty, with no error. The names are lowercase and Angular passes them to addEventListener verbatim, so camel-casing one means it never fires.

  • (change)="onChange($event.detail)"

Accessibility

  • Renders a native <button role="switch"> with aria-checked reflecting state.
  • Keyboard and activation come for free; Space/Enter toggle.
  • The disabled attribute disables the underlying button.
  • Visible focus ring on the track via --focus-ring-* tokens.

Theming surface

Every public token this component reads, extracted from its source at build time, split by blast radius: the hooks that belong to this component, then the shared and system tokens it consumes alongside everything else. The Resolves to column walks each token's real lineage — component → semantic → primitive → raw value — so you can see exactly where re-pointing it lands. A spoke re-skins by overriding these in its theme-<slug>.css; component internals are never edited. No hook for what you need? File it with /request-lego.

Type roles it names

This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.

RoleRe-pointReach
.typography-body-md
  • --typography-body-md-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-body-md-font-size clamp(0.75rem, 0.66rem + 0.44vw, 0.9375rem) via --font-size-200
  • --typography-body-md-font-weight 350 via --typography-font-weight-regular → --font-weight-350
  • --typography-body-md-letter-spacing 0.01em via --letter-spacing-default
  • --typography-body-md-line-height 1.6 via --line-height-normal
+28 more components esa-app-shell, esa-breadcrumbs, esa-card, esa-checkbox, esa-checkbox-group, esa-collapsible, esa-combobox, esa-command-palette, esa-confirm-dialog, esa-container, esa-danger-zone, esa-dialog, esa-dropdown-menu, esa-empty-state, esa-entity-search, esa-form-field, esa-header-nav, esa-input-tag, esa-nav-dropdown, esa-page-header, esa-popover, esa-progress-bar, esa-radio-group, esa-select, esa-side-dialog, esa-snackbar-item, esa-tab-layout, esa-textarea

Wired to this component

None. This component has no hooks of its own — it themes entirely through the shared tokens below, so every override here also moves its siblings.

Shared tokens it reads

Owned by a family or by the semantic layer. Still overridable — but scope the override (esa-foo { --form-border-color: … }) unless you mean to move everything that reads it. Reach says what else that is.

Token Reach Resolves to
--focus-ring-color component focus ring group · +34 more #3e9b4f via --color-border-default-focus → --color-grass-10
--focus-ring-offset component focus ring group · +31 more 2px
--focus-ring-width component focus ring group · +35 more 2px via --border-width-focus → --border-width-200
--color-background-brand semantic every component #46a758 via --color-grass-9
--color-background-elevation-raised semantic every component #fcfcfc via --color-gray-1
--color-border-default-strong semantic every component #bbbbbb via --color-gray-8
--color-content-default semantic every component #202020 via --color-gray-12
--elevation-1 semantic every component 0 via --shadow-offset-x
--radius-pill semantic every component 9999px via --radius-full
--transition-fast semantic every component 150ms via --duration-150
--spacing-200 primitive every component 0.5rem