diff --git a/site/public/images/switch-attribute/0_1_switch.gif b/site/public/images/switch-attribute/0_1_switch.gif new file mode 100644 index 000000000..185275035 Binary files /dev/null and b/site/public/images/switch-attribute/0_1_switch.gif differ diff --git a/site/public/images/switch-attribute/BlinkOnSwitch.gif b/site/public/images/switch-attribute/BlinkOnSwitch.gif new file mode 100644 index 000000000..31b6b4038 Binary files /dev/null and b/site/public/images/switch-attribute/BlinkOnSwitch.gif differ diff --git a/site/public/images/switch-attribute/X_CHECK_Switch.gif b/site/public/images/switch-attribute/X_CHECK_Switch.gif new file mode 100644 index 000000000..b621d418e Binary files /dev/null and b/site/public/images/switch-attribute/X_CHECK_Switch.gif differ diff --git a/site/public/images/switch-attribute/Y_N_Switch.gif b/site/public/images/switch-attribute/Y_N_Switch.gif new file mode 100644 index 000000000..aba490067 Binary files /dev/null and b/site/public/images/switch-attribute/Y_N_Switch.gif differ diff --git a/site/public/images/switch-attribute/default-switch.png b/site/public/images/switch-attribute/default-switch.png new file mode 100644 index 000000000..e1cded6bc Binary files /dev/null and b/site/public/images/switch-attribute/default-switch.png differ diff --git a/site/public/images/switch-attribute/element_switches.gif b/site/public/images/switch-attribute/element_switches.gif new file mode 100644 index 000000000..759d45023 Binary files /dev/null and b/site/public/images/switch-attribute/element_switches.gif differ diff --git a/site/public/images/switch-attribute/labels_Switch.gif b/site/public/images/switch-attribute/labels_Switch.gif new file mode 100644 index 000000000..80cbef55c Binary files /dev/null and b/site/public/images/switch-attribute/labels_Switch.gif differ diff --git a/site/public/images/switch-attribute/localization_switch.gif b/site/public/images/switch-attribute/localization_switch.gif new file mode 100644 index 000000000..d42b33632 Binary files /dev/null and b/site/public/images/switch-attribute/localization_switch.gif differ diff --git a/site/public/images/switch-attribute/styled-switch-gradient.png b/site/public/images/switch-attribute/styled-switch-gradient.png new file mode 100644 index 000000000..394165f6e Binary files /dev/null and b/site/public/images/switch-attribute/styled-switch-gradient.png differ diff --git a/site/src/pages/components/switch.attribute.explainer.mdx b/site/src/pages/components/switch.attribute.explainer.mdx new file mode 100644 index 000000000..f8e14b220 --- /dev/null +++ b/site/src/pages/components/switch.attribute.explainer.mdx @@ -0,0 +1,643 @@ +--- +menu: Active Proposals +name: Switch Attribute (Explainer) +path: /components/switch.attribute.explainer +pathToResearch: /components/switch +layout: ../../layouts/ComponentLayout.astro +authors: + - name: Andres Regalado Rosas + url: https://github.com/andresrega-msft +--- + +## Overview + +Switch controls (also called toggles) are binary on/off controls that take immediate effect, as opposed to checkboxes which typically require form submission. They are common across native platforms (iOS, Android, Windows, macOS) and web applications (settings pages, feature toggles, consent dialogs, dark mode switches). + +Despite being one of the most commonly implemented UI components on the web, there is no native HTML element or attribute for switches. The [Open UI component research](https://open-ui.org/components/switch.explainer/) identified switches as a high-priority gap in the platform. The [WHATWG HTML PR #9546](https://github.com/whatwg/html/pull/9546) proposes filling this gap by adding a `switch` attribute to ``. + +```html + +``` + +![Switch appearance (Chromium)](/images/switch-attribute/default-switch.png) + +### Alternative proposal + +There is a [switch element proposal at Open UI](https://open-ui.org/components/switch.explainer/) that would introduce a standalone `` element. This explainer focuses on the attribute approach (``). See [Alternatives Considered](#alternatives-considered) for a comparison. + +An implementation of the attribute approach has shipped in stable Safari since version 17.4 (https://github.com/whatwg/html/pull/9546#issuecomment-1865357407). + +### Use Cases + +A switch can be used anywhere a user toggles a binary state with immediate effect: + +- Settings pages (dark mode, notifications, privacy preferences) +- Feature toggles (enable/disable functionality) +- Consent dialogs (accept/reject cookies) +- Accessibility preferences (reduce motion, high contrast) + +### Non-Goals + +- Replacing component library switches for applications that need highly custom behavior +- Providing an API that covers every possible switch variant (loading states, multi-position switches, etc.) +- Breaking backward compatibility with existing checkbox behavior + +--- + +## User-Facing Problem + +End-users encounter toggle switches on nearly every website and app (settings pages, preferences, feature toggles, consent dialogs). These controls look and behave consistently across native platforms (iOS, Android, desktop OS settings), but on the web every implementation is different. + +This inconsistency leads to: + +- **Unreliable accessibility**: Screen reader announcements vary depending on how the developer built the switch. Some announce "checkbox," some announce "switch," and some announce nothing useful. +- **Broken keyboard navigation**: Custom implementations often miss keyboard handling, leaving keyboard-only users unable to toggle settings. +- **Inconsistent interaction patterns**: Some switches toggle on click, some on drag, some on both. Users cannot predict behavior. +- **Performance cost**: Users on low-end devices pay for JavaScript bundles that reimplement what should be a native control. + +Today, developers have three options to implement switches, none of which adequately serve end-users: + +### 1. JavaScript component libraries + +```jsx +// React + Material UI +import Switch from '@mui/material/Switch'; + +function Settings() { + const [checked, setChecked] = useState(false); + return ( + setChecked(e.target.checked)} />} + label="Dark mode" + /> + ); +} +``` + +Requires a framework, a component library dependency, and JavaScript for basic toggle functionality. Accessibility quality depends entirely on the library author. + +### 2. CSS-only switches using hidden checkboxes + +```html + +``` + +```css +.switch { + position: relative; + display: inline-block; + width: 60px; + height: 34px; +} +.switch input { + opacity: 0; + width: 0; + height: 0; + position: absolute; +} +.slider { + position: absolute; + inset: 0; + background-color: #ccc; + border-radius: 34px; + transition: 0.4s; + cursor: pointer; +} +.slider::before { + content: ""; + position: absolute; + height: 26px; + width: 26px; + left: 4px; + bottom: 4px; + background-color: white; + border-radius: 50%; + transition: 0.4s; +} +input:checked + .slider { background-color: #2196F3; } +input:checked + .slider::before { transform: translateX(26px); } +``` + +The input is visually hidden; the "switch" is a sibling `` styled to look like a toggle. This approach is fragile, hard to maintain, and screen readers announce it as "checkbox" rather than "switch." + +### 3. `role="switch"` on generic elements + +```html +
+ + + + +
+``` + +```javascript +const sw = document.getElementById('theme-switch'); +sw.addEventListener('click', () => { + const checked = sw.getAttribute('aria-checked') === 'true'; + sw.setAttribute('aria-checked', String(!checked)); +}); +sw.addEventListener('keydown', (e) => { + if (e.key === ' ' || e.key === 'Enter') { + e.preventDefault(); + sw.click(); + } +}); +``` + +Developers must reimplement keyboard handling, state management, and ARIA attributes from scratch. Form participation requires additional workarounds like `ElementInternals` or hidden inputs, making the pattern error-prone. + +--- + +**All three approaches** lead to inconsistency, accessibility gaps, and unnecessary JavaScript payload for end-users. + +--- + +## Design + +### Proposed Approach + +```html + +``` + +Adding the `switch` attribute to a checkbox changes its appearance to a switch control. The control exposes pseudo-elements for styling, aligned with the [CSS Forms spec](https://drafts.csswg.org/css-forms-1/): + +- **`::slider-track`** — the background track of the switch +- **`::slider-thumb`** — the sliding knob/indicator + +> **Note:** These names follow the `::slider-*` convention from [css-forms-1](https://drafts.csswg.org/css-forms-1/), which treats switches as slider-like controls. Naming is subject to change as the spec evolves. Whether these pseudo-elements are always exposed or only when `appearance: base` is set is still under discussion. + +### Basic Usage + +```html + + + + + + + + +``` + +![Switch appearance (Chromium)](/images/switch-attribute/default-switch.png) + +```css +/* Custom track */ +input[switch]::slider-track { + background: linear-gradient(135deg, #667eea, #764ba2); +} + +/* Custom size */ +input[switch] { + width: 56px; + height: 28px; +} + +/* Custom thumb */ +input[switch]::slider-thumb { + background: linear-gradient(135deg, #f6d365, #fda085); + box-shadow: 0 2px 6px rgba(0,0,0,0.3); +} +``` + +![Styled switch with gradient](/images/switch-attribute/styled-switch-gradient.png) + +### Form Participation + +The switch behaves identically to a checkbox for form submission: + +```html +
+ + +
+``` + +When checked, submits `darkmode=on`. When unchecked, omits the field (standard checkbox behavior). + +### Animation + +The UA stylesheet provides smooth transitions out of the box: + +```css +/* UA default */ +input[switch]::slider-track { + container-type: size; + transition: background-color 0.3s ease; +} +input[switch]::slider-thumb { + left: 2px; + transition: transform 0.3s ease, background-color 0.3s ease; +} +input[switch]:checked::slider-thumb { + transform: translateX(calc(100cqw - 100% - 4px)); +} +``` + +Using container query units (`cqw`) and self-referencing percentages in transforms allows the thumb's checked position to be calculated dynamically for any switch and thumb size, enabling smooth animation without JavaScript. + +![Switch animation example](/images/switch-attribute/BlinkOnSwitch.gif) + +### APIs + +#### Properties and Attributes + +| Property Name | Attribute Name | Type | Default Value | Description | +|---|---|---|---|---| +| `checked` | `checked` | `boolean` | `false` | Indicates if the switch is in the "on" state. | +| `value` | `value` | `string` | `"on"` | The value submitted with the form when checked. | +| `name` | `name` | `string` | `""` | The name of the control for form submission. | +| `disabled` | `disabled` | `boolean` | `false` | Disables the control, preventing user interaction. | +| `required` | `required` | `boolean` | `false` | Indicates the switch must be checked for form validation. | +| `form` | `form` | `string` | `""` | Associates the element with a form whose `id` is this value. | +| `switch` | `switch` | `boolean` | `false` | When present on a checkbox, renders as a switch control. | + +#### Events + +| Event Name | Bubbles | Composed | Cancellable | Description | +|---|---|---|---|---| +| `change` | `true` | `true` | `false` | Fired when the checked state changes. | +| `input` | `true` | `true` | `false` | Fired when the user commits a value change. | + +#### Pseudo-elements + +| Pseudo-element | Description | +|---|---| +| `::slider-track` | The background container of the switch. Supports `container-type: size`. | +| `::slider-thumb` | The sliding indicator. Positioned absolutely within the track. | + +### What the Attribute Approach Cannot Do + +There are use cases that the attribute approach cannot handle. These require real DOM children inside the switch, which is not possible because `` cannot have child elements. + +- **Loading spinner in the thumb**: showing a rotating animation while an async action completes +- **Avatar or photo in the thumb**: e.g. a user profile picture that slides with the toggle +- **Multi-line track content**: a title + subtitle inside the track +- **Nested interactive elements**: e.g. a settings button or slider embedded in the thumb +- **Tooltip anchored to the thumb**: e.g. a popover that follows the thumb position + +![Element approach use cases](/images/switch-attribute/element_switches.gif) + +These are real limitations. However, none of these patterns appear in the popular component libraries surveyed, suggesting they are edge cases rather than common needs. The alternatives section below describes approaches that could handle these cases in the future. + +### What the Attribute Approach Can Do (with CSS) + +There are other use cases which would be easier to implement with child elements, but are still achievable with the attribute approach: + +#### Track text + +Using positioned spans with `:has()`: + +```html + +``` + +```css +.switch-label { + position: relative; + display: inline-block; + --w: 56px; + --h: 28px; + --m: 3px; +} +.switch-label input[switch] { + width: var(--w); + height: var(--h); +} +.on-text, .off-text { + position: absolute; + top: var(--m); + width: calc(var(--w) - var(--h) * 0.75); + height: var(--h); + display: flex; + align-items: center; + justify-content: center; + font-size: 12px; + font-weight: 700; + color: white; + pointer-events: none; + transition: opacity 0.2s ease, transform 0.2s ease; +} +.on-text { left: var(--m); opacity: 0; transform: translateX(6px); } +.off-text { right: var(--m); opacity: 1; transform: translateX(0); } +.switch-label:has(input:checked) .on-text { opacity: 1; transform: translateX(0); } +.switch-label:has(input:checked) .off-text { opacity: 0; transform: translateX(-6px); } +.switch-label input[switch]::slider-track { background-color: #ef4444; } +.switch-label input[switch]:checked::slider-track { background-color: #22c55e; } +``` + +
+ +![Track text demo](/images/switch-attribute/Y_N_Switch.gif) + +
+ +This same technique enables **localization**. Since the labels are regular DOM elements, any i18n system can update them: + +```html + + +``` + +```js +const translations = { + en: { on: 'On', off: 'Off' }, + es: { on: 'Sí', off: 'No' }, + zh: { on: '开', off: '关' }, + ar: { on: 'نعم', off: 'لا' }, + ja: { on: 'オン', off: 'オフ' } +}; +document.getElementById('lang-picker').addEventListener('change', (e) => { + const lang = e.target.value; + document.querySelectorAll('[data-i18n]').forEach(el => { + el.textContent = translations[lang][el.dataset.i18n]; + }); +}); +``` + +Existing tooling (i18next, FormatJS, gettext) can find and translate these without special handling. + +
+ +![Localization demo](/images/switch-attribute/localization_switch.gif) + +
+ +#### Thumb icons + +Using `background-image` on `::slider-thumb`: + +```css +input[switch]::slider-thumb { + background-image: url("cross-icon.svg"); + background-size: 60%; + background-position: center; + background-repeat: no-repeat; +} +input[switch]:checked::slider-thumb { + background-image: url("check-icon.svg"); +} +``` + +
+ +![Thumb icons demo](/images/switch-attribute/X_CHECK_Switch.gif) + +
+ +#### Thumb text + +Using SVG text in `background-image`: + +```css +input[switch]::slider-thumb { + background-image: url("data:image/svg+xml,...0..."); + background-size: 80%; + background-position: center; + background-repeat: no-repeat; +} +input[switch]:checked::slider-thumb { + background-image: url("data:image/svg+xml,...1..."); +} +``` + +
+ +![Thumb text demo](/images/switch-attribute/0_1_switch.gif) + +
+ +#### External labels + +Using sibling spans with `:has()`: + +```html + +``` + +```css +label:has(input:checked) .on-label { color: blue; } +label:not(:has(input:checked)) .off-label { color: blue; } +``` + +
+ +![External labels demo](/images/switch-attribute/labels_Switch.gif) + +
+ +--- + +## Behavior + +### States and Interactions + +| State Group | States | Initial State | Description | Interaction/Transition | +|---|---|---|---|---| +| `checked` | `true`/`false` | `false` | The current on/off state of the switch. | Changed on click, touch, Space key (when focused), or drag gesture. | +| `disabled` | `true`/`false` | `false` | When `true`, disables the control. | No interaction. Controlled programmatically. | +| `focused` | `true`/`false` | `false` | Whether the switch has keyboard focus. | Tab key navigation. | + +### User Interaction + +- **Click/tap**: Toggles the switch +- **Space**: Toggles the switch when focused +- **Drag**: Slide the thumb to toggle (similar to ``) + +### Accessibility + +The `switch` attribute maps to `role="switch"` in the accessibility tree, as specified in [ARIA in HTML](https://www.w3.org/TR/wai-aria-1.2/#switch). + +- **Screen readers**: Announce the control as a "switch" rather than a "checkbox" +- **Keyboard**: Space key toggles (same as checkbox) +- **States**: `aria-checked` is automatically mapped from the `checked` property +- **Labels**: Standard `